Getting Started
Conventions
Every object you send carries an externalId, your identifier, in your format. All paths address matches by externalId.
Your IDs, not ours
Every object you send carries an externalId, your identifier, in your format. We store it against our own record and echo it back on every response, so you never need to persist a Spectatr.ai ID. All paths address matches by externalId.
externalId is 1 to 128 characters, matching [A-Za-z0-9_.:-]+. It must never be reused for a different object.
Sport
sport identifies the discipline, and it is the abbreviation, not the display name. It is not a fixture identifier; your per-game ID is always externalId on a match.
| Sport | Send this |
|---|---|
| Rugby | rugby |
| Football | football |
| Hurling | hurling |
| Gaelic Football | gaelic-football |
| Camogie | camogie |
Case is ignored, so RUGBY resolves the same as rugby. The hyphen is not: gaelic-football resolves, Gaelic Football is rejected. Note that football and gaelic-football are two different sports here, not two names for one. We match the value against the sports on your licence, so an unrecognised one fails with 403 sport_not_licensed, and a sport you are not licensed for fails the same way. Loudly, at publish time, rather than quietly filing fixtures under the wrong game.
Timestamps
All times are Unix epoch milliseconds, UTC. Not seconds. A seconds-precision value would place a fixture in 1970, so we reject any timestamp outside a plausible range rather than accept it.
Kickoff and ingest are separate times
startTime on a match is kickoff. ingestStartTime on a source is when your feed comes up. We do not derive one from the other: moving kickoff does not move the connect, and a source with no ingestStartTime is rejected rather than defaulted. Set it to whenever your encoder is actually live, typically well before kickoff, so the handshake is proven before it matters.
Idempotency
POST /schedule is a full upsert keyed on your externalId values. Sending it twice is safe; sending it with changes applies the changes. Retry freely on network failure, you will not create duplicates.
Locked once live
A match whose ingest state is STARTING, STARTED or ENDED rejects changes to its kickoff time, name or roster with 409. You cannot move the kickoff of a game already being recorded.