Maestro creates event ingestion rules and templates

You publish a feed of upcoming events. Maestro turns each one into a configuration document your SDK fetches, addressed by your own event ID and kept up to date as your feed and your settings change.

• Read-only. Maestro pulls; you never push.
• No ID mapping on your side. Your SDK fetches by the identifier your systems already use.

How templates decide what goes into each configuration is covered in Templates. This page is the setup conversation and what to expect once it is live.

The contract

Each event's configuration is published at a path built from your own identifier for that event:

/sites/{siteId}/metadata/{yourEventId}.json

Your Site ID is fixed and issued once. The event ID is whatever your feed calls it. Pass the same value your own systems use and the path resolves. Maestro provides the CDN base URL for each environment during onboarding.

The document contains the resolved configuration for that event: the features enabled on it, their settings, the content attached, and per-platform differences where they apply. Anything you asked Maestro to carry from your feed is in there too. The exact schema is shared alongside the SDK documentation. It is stable, and additive changes are the only ones made without notice.

What Maestro needs from you

A one-time setup conversation. Work through it with your Maestro contact and the integration is done.

Feed endpoint (required)

A URL Maestro can call over HTTPS. REST (GET or POST) or GraphQL are both first-class. A staging or pre-production feed too, if you have one, so the integration can be validated before it reaches your live SDK traffic.

Example: https://api.example.com/v2/schedule/nfl plus a sandbox equivalent.

Authentication (required)

Tell Maestro which one your feed uses:

• Bearer token, sent as Authorization: Bearer <token>
• API key, in a header of your choosing, e.g. x-acme-apikey
• Basic auth, a username and password pair
• HMAC-signed requests, a shared secret Maestro signs with
• None, if the feed is already public

Also how often the credential rotates and how you would deliver a new one. Credentials are stored encrypted, per environment, separate from the feed configuration.

Polling cadence and limits (required)

How often Maestro may call you, and any ceiling to respect. Maestro honours a sustained rate and a burst allowance, so a limit on your side becomes a setting on Maestro's rather than a support ticket later.

This also sets how quickly a change in your feed reaches your SDK: poll every 20 minutes and a kickoff-time change can take that long to publish.

Example: poll every 20 minutes, max 30 requests per minute, burst 5.

A sample payload (required)

One real response captured from the live feed. The single most useful thing you can send; Maestro maps directly off it. A sample containing unusual cases (an event missing a venue, a doubleheader, a postponed fixture) is worth more than a clean one.

Three fields per event (required)

Inside that payload Maestro needs to point at the list of events, then at three things on each one. They can be nested anywhere and named anything.

• A unique, stable identifier. This becomes the key your SDK fetches by; see the event identifier below.
• A display name, what a viewer would recognise the event as.
• A start time, ISO 8601, with an explicit timezone or offset.

Example: events at data.games[]; each has gameId, matchup, startDateTime.

Anything else worth carrying (optional)

Any other field in your payload can travel through into the configuration document, where your SDK can read it and where it can drive per-event behaviour through templates. Fields missing on a given event are skipped quietly, so an inconsistent feed is fine.

Paging (optional)

If the feed returns everything in one response, skip this. If it pages, say which style and how the end is signalled:

• Page and size parameters, plus a total count in the response.
• Cursor-based, plus the fields carrying the next cursor and a has-more flag.

How far ahead the feed sees (optional)

Maestro fetches a rolling window rather than your whole history. Say how far in advance an event lands in the feed and the window is set wider, so a configuration document is always in place before your SDK asks for it.

Example: fixtures published 7 days ahead, so Maestro asks for a 10-day window.

The event identifier is your SDK's lookup key

This one field does double duty: it is how Maestro tells an event it has already configured from a new one, and it is the address your SDK fetches by. Get it right and your app needs no mapping layer at all; it already holds the ID.

It must stay identical for the entire life of the event: across every poll, and through changes to kickoff time, venue, broadcaster, or status. If it changes, Maestro cannot tell it is the same event. A second configuration is published under the new ID, the old file stops being updated, and an SDK still asking for the old ID silently receives stale configuration.

A stable primary key from your own system is ideal. A value composed of things that can change, such as a slugified matchup, anything with the date in it, or a row position, is not.

How a change reaches your SDK

1. A new event appears in your feed. Within one poll cycle Maestro creates its configuration and publishes the JSON. The file exists from that moment, well before the event starts, as long as your feed publishes ahead of time.
2. An event changes in your feed. Kickoff time moves, a broadcaster changes, status flips. Maestro picks it up on the next poll, updates the configuration, and republishes the same file at the same path. Your SDK sees the change on its next fetch.
3. Your team changes settings in the Admin. Same result by a different route: the configuration is rebuilt and the file republished. No deploy, no release, no call to Maestro.
4. An event leaves your feed. Nothing is deleted. The configuration and its JSON stay exactly as they are, so an SDK still holding that ID keeps working.

Publishing is asynchronous

A change is queued, rendered, uploaded, and then propagated through the CDN. Expect a change to be visible to your SDK within about a minute, not instantly, and treat that as a floor rather than a guarantee under heavy load.

Two things follow from that: do not assume a change made in the Admin is readable on the very next fetch, and do not treat a brief window of older configuration as an error. If something has not appeared after a few minutes, that is worth raising with Maestro.

What Maestro does not need

• No integration to build. If the feed already exists, your engineering work may be zero. Maestro adapts to your payload rather than asking you to produce one.
• No ID mapping. Your SDK fetches by the identifier your own systems already use. There is nothing to store or translate.
• No push, webhooks, or callbacks. Maestro polls you. You never have to notify Maestro that something changed.
• No per-event calls. One list endpoint covers the whole schedule.
• No access to your systems. Read-only HTTPS against one endpoint, with a credential you issue and can revoke at any time.
• No write access, ever. Nothing Maestro does can alter data on your side.

When something goes wrong

Situation	What your SDK sees
Your feed is unreachable or returns an error	Already-published configuration is untouched and keeps serving normally. New events are not picked up until the feed recovers, and changes to existing events are delayed by the same amount.
One event is missing a required field	That event is skipped; the rest of the response is processed normally. No configuration is published for it, so a fetch by that ID returns nothing. One malformed record never blocks the batch.
A carried field is missing on some events	Absent from that event's document, present on the others. Optional fields are genuinely optional; read them defensively.
An event's identifier changes	A second document appears under the new ID. The original stops being updated but keeps serving, so an SDK holding the old ID gets stale configuration with no error. The failure mode worth designing against.
An event matches no template	Nothing is published for it, so a fetch by that ID returns nothing. Usually a field the matching rules expect is missing from that event. A catch-all template prevents it entirely.
A change was made moments ago	Possibly the previous version, for up to a minute or so, while the render and CDN propagation complete. Expected, not an error.

Worked example

One record from your feed:

{
  "data": {
    "games": [
      {
        "gameId": "401547417",
        "matchup": "Chiefs at Bills",
        "startDateTime": "2026-10-12T20:15:00Z",
        "league": { "id": "nfl", "name": "National Football League" },
        "venue": { "name": "Highmark Stadium" },
        "network": "CBS",
        "status": "scheduled"
      }
    ]
  }
}

What your SDK requests:

/sites/{siteId}/metadata/401547417.json

keyed by	gameId, unchanged
name	Chiefs at Bills
starts	12 Oct 2026, 20:15 UTC
features	from template plus overrides
carried	league, venue, network, status

Three fields are mapped: gameId, matchup, startDateTime. The rest travel through into the document. Your app already knows 401547417; that is the whole lookup.

Questions about a specific feed are best answered against a real sample payload. Send one and Maestro will come back with the exact mapping, the document paths it produces, and anything that needs a decision from you.