RefWhistle API
A read-only, key-authenticated API over the match fixtures, published coaching reports, and live-coaching timeline. Every response is scoped to exactly one tenant and, optionally, a subset of its associations.
Authentication
Every key is minted by a RefWhistle system administrator (see Requesting access) and locked to exactly one tenant, an optional subset of that tenant's associations, and an explicit set of scopes. There is no self-serve signup and no OAuth flow. A key is simply a bearer credential.
Key format
Every key looks like this:
refwhistle<keyId>-<secret>
The keyId is a 12-character non-secret identifier for your key. It's used to track metrics
and audit logs, so it's fine to share publicly, for example in a support request. secret is
shown to you exactly once, at mint or rotation time. RefWhistle stores only the secret's SHA-256 hash; if
you lose it, the fix is a rotation, not a lookup.
Scopes
A key only sees what its scopes grant, independent of the tenant/association lock above:
| matches:read | /matches, /matches/{matchId} |
| reports:read | /reports (also needs matches:read), /reports/published, /reports/{reportId} |
| coach-data:read | /coach-data/{matchId} |
| incidents:read | /incidents/{matchId} |
| kmis:read | /kmis |
Send it either way
Both are accepted on every authenticated route. Pick whichever your HTTP client makes more natural.
Authorization: Bearer refwhistleaB3dE7gH9kLp-xR2k...
X-API-Key: refwhistleaB3dE7gH9kLp-xR2k...
A missing, malformed, unrecognised, or revoked key all return the identical 401 unauthorized.
This is deliberate, so a script trying to enumerate valid keys learns nothing from the response shape. A key that
exists but has passed its expiresAt returns 401 key_expired with the expiry date
in detail. See Errors for the full envelope.
Endpoints
Every response is application/json. List endpoints return
{ "data": [...], "pagination": {...} }; single-resource endpoints return
{ "data": {...} }. Every successful response also carries the rate-limit headers described
under Rate limits.
GET
/api/v1/meta
no scope required
▸
Introspect the calling key itself: its tenant, granted associations, scopes, and configured rate limit. Useful as a first call when wiring up a new integration, and to confirm a rotation took effect.
{
"data": {
"keyId": "aB3dE7gH9kLp",
"tenantId": "tenant_whistle_demo",
"associationIds": ["assoc_9f3k2m7q1x8p"],
"scopes": ["matches:read", "reports:read", "coach-data:read", "incidents:read", "kmis:read"],
"rateLimitPerHour": 1000
}
}
GET
/api/v1/matches
matches:read
▸
Lists matches in the key's tenant, newest first (date desc, time desc).
Filters are optional and AND-combined, except match_id. When present, match_id
ignores every other filter and is served as a batched by-id lookup rather than a query.
| Param | Type | Description |
|---|---|---|
| match_id | string[] multi, max 20 | Repeat the param or comma-list. Ignores every other filter below. |
| association | string | One associationId. Must be within the key's grant, if restricted. |
| date | date | Exact match date, YYYY-MM-DD. |
| date_from | date | Inclusive lower bound. |
| date_to | date | Inclusive upper bound. |
| status | string[] multi | upcoming · live · completed · canceled |
| division | string | Free-text match, 1-200 characters. |
| competition | string | Free-text match, 1-200 characters. |
| official_id | string | Matches where this user id is an appointed official. |
| updated_since | date-time | ISO 8601 date or date-time. Switches to incremental-sync mode: ordered updatedAt asc instead of date desc, time desc, with its own cursor. Mutually exclusive with date/date_from/date_to, but composable with every other filter above. See Sync strategy. |
| page_size | integer | 1-100, default 50. |
| cursor | string | Opaque token from a previous pagination.next_cursor. |
Response codes
SerializedMatch objects + pagination.invalid_parameter. See detail.parameter.unauthorized / key_expired.scope_not_permitted / association_not_permitted.rate_limited. See Retry-After.
GET
/api/v1/matches/{matchId}
matches:read
▸
One match, with its full public field set plus videoUrl and
streamCalibration.youtubeUrl when present. A match in a different tenant returns
404, never 403, which would confirm it exists elsewhere. A match outside an
association-restricted key's grant returns 403 association_not_permitted.
Each entry in appointments carries the official's userId and
name, plus refReflectUserId: their RefReflect id when
their account is linked to one, otherwise null. The same field appears on the
list response.
{
"data": {
"id": "8sZ3xQ1mPn7YkLtRj2Vc",
"homeTeam": "Northside FC", "awayTeam": "Coastal United",
"date": "2026-09-26", "time": "15:00", "status": "upcoming",
"competition": "NPL", "division": "Premier League",
"associationId": "assoc_9f3k2m7q1x8p",
"homeScore": null, "awayScore": null, "isReported": false,
"appointments": { "center": { "userId": "6mK2...", "name": "J. Alvarez", "refReflectUserId": 18734 } },
"timing": { "status": "not_started", "halfLengthMins": 45, "extraTimeEnabled": false },
"updatedAt": "2026-09-19T22:14:03.000Z",
"videoUrl": null, "streamCalibration": null
}
}
GET
/api/v1/reports
matches:read + reports:read
▸
The reporting status board: every match in a date window and where its reports are up to, in one request per page. Each row is
a match: its teams, kick-off and venue, its overall reportingStatus
(submitted · partial · draft · pending, the same rule
as the admin Reports page), and every owed report's status (published ·
draft · missing), official and responsible coach. It never returns report
content. Once a report is published its report_id is set, and you fetch the content from
/reports/{reportId}. Poll this endpoint instead of crawling every
report: call it once an hour (with no params it covers the last week), compare each row's reportingStatus or
lastActivityAt with your previous poll, and fetch only the newly published
report_ids.
Takes /matches's filters, ordering and cursor
(match_id, association, date, date_from,
date_to, status, division, competition,
official_id, page_size, cursor). With no date,
date_from, date_to or match_id it covers the last 7 days
in your tenant's timezone (today and the 6 days before), and the response's window tells you
which dates it used. It rejects updated_since, because saving a report doesn't change the
match's updatedAt. Draft report content is never returned here or anywhere else; the
board only shows that a draft exists.
{
"data": [{
"match": {
"id": "8sZ3xQ1mPn7YkLtRj2Vc",
"homeTeam": "Northside FC", "awayTeam": "Coastal United",
"date": "2026-10-25", "time": "13:00", "venue": "Hnry Stadium",
"competition": "A-League Men", "associationId": "assoc_9f3k2m7q1x8p", "status": "completed"
},
"reportingStatus": "partial",
"counts": { "required": 4, "published": 3, "draft": 1, "outstanding": 1 },
"coach": { "userId": "9jH4kR7wLp2VnQm8TfB3", "name": "J. Mannella" },
"reports": [
{ "role": "center", "required": true, "status": "published",
"official": { "userId": "4tR8pW2nKq9XmLb1JhY7", "name": "J. Alvarez" },
"coach": { "userId": "9jH4kR7wLp2VnQm8TfB3", "name": "J. Mannella" },
"report_id": "8sZ3xQ1mPn7YkLtRj2Vc~4tR8pW2nKq9XmLb1JhY7",
"publishedAt": "2026-10-26T01:02:00.000Z", "lastActivityAt": "2026-10-26T01:02:00.000Z" },
{ "role": "var", "required": true, "status": "draft",
"official": { "userId": "2bN7...", "name": "S. Kim" },
"coach": { "userId": "7cQ1...", "name": "K. Griffiths-Jones" },
"report_id": null, "publishedAt": null, "lastActivityAt": "2026-10-25T23:40:00.000Z" }
],
"lastActivityAt": "2026-10-26T01:02:00.000Z"
}],
"window": { "date_from": "2026-10-20", "date_to": "2026-10-26" },
"pagination": { "page_size": 50, "next_cursor": null, "has_more": false }
}
GET
/api/v1/reports/published
reports:read
▸
A feed of published coaching reports only, ordered by
publishedAt desc. Draft reports never appear here, and no parameter widens that. This was
GET /reports until the status board took that path. To find out
what changed in a given week, poll the board instead.
summary is the report's precomputed summary (its shape depends on the report's coaching format).
overallMark is the report's weighted overall mark, or null when the report's format defines no
mark for this match and role (for example the 4th Official). It is available to any key with reports:read; no extra
scope is needed. value is out of outOf and is null while status is
incomplete (a weighted section is still ungraded). In breakdown, weight is the section's
share of the total (0 to 1) and points its contribution out of outOf; both are null for an
ungraded or N/A section.
refReflectUserId is the referee's RefReflect id when their
account is linked to one, otherwise null. The detail response carries it too.
| Param | Type | Description |
|---|---|---|
| published_since | date-time | ISO 8601 date or date-time. Inclusive lower bound on publishedAt. |
| published_until | date-time | Same format. Inclusive upper bound. |
| referee_id | string | Reports for one referee. |
| coach_id | string | Reports authored by one coach. |
| match_id | string | A single matchId (not a multi/comma-list, unlike /matches's own match_id). |
| page_size | integer | 1-100, default 50. |
| cursor | string | Opaque token from a previous pagination.next_cursor. |
{
"data": [{
"report_id": "8sZ3xQ1mPn7YkLtRj2Vc~4tR8pW2nKq9XmLb1JhY7",
"matchId": "8sZ3xQ1mPn7YkLtRj2Vc",
"refereeId": "4tR8pW2nKq9XmLb1JhY7",
"refReflectUserId": 18734,
"coachId": "9jH4kR7wLp2VnQm8TfB3",
"officialType": "center",
"publishedAt": "2026-09-19T22:14:03.000Z",
"reportFormatId": "fmt-1789001449764-e4t3z0",
"summary": {
"overall": { "tierId": "generally", "tierName": "Above Average" },
"counts": { "logs": 61, "kmi": 3, "cards": 4, "strengths": 5, "improvements": 2 }
},
"overallMark": {
"value": 75.28,
"outOf": 100,
"label": "Overall Mark",
"status": "complete",
"scheme": "ALM 2026/27",
"breakdown": [
{ "section": "Application of Law", "grade": "Above Average", "weight": 0.2393, "points": 21.93 },
{ "section": "Decision Making Accuracy", "grade": "Expected", "weight": 0.2222, "points": 13.35 }
]
}
}],
"pagination": { "page_size": 50, "next_cursor": null, "has_more": false }
}
GET
/api/v1/reports/{reportId}
reports:read
▸
One published report. reportId is the composite
report_id a list response already gave you: {matchId}~{refereeId}. A report
in a different tenant and a report that exists but isn't published yet return the exact same
404; the response never distinguishes the two.
| Param | Type | Description |
|---|---|---|
| include | string | Pass snapshots to also include gradingSpecSnapshot/blueprintSnapshot. Any other value is simply ignored, never a 400. |
Detail adds narratives, kpiAnswers, profileMarks,
overallCoachingComments, finalSummary, values, the full
logs[] array (same shape as /coach-data's), videoUrl,
refereeResponse, and formatVersion, the report blueprint's version, needed to
safely interpret a custom format's free-form values/log fields. It also carries the same
overallMark object as the feed.
GET
/api/v1/coach-data/{matchId}
coach-data:read
▸
The live-integration endpoint: every log captured for the match, plus a compact
match state. Responses are cached for 20 seconds while the match is
live and 5 minutes otherwise, so polling more often than that returns the same data. The
response tells you whether you got a cached copy and how old it is.
{
"data": {
"match": {
"id": "8sZ3xQ1mPn7YkLtRj2Vc", "status": "live",
"timing": { "firstHalfStartTime": 1758276600000, "secondHalfStartTime": null,
"extraTimeFirstHalfStartTime": null, "extraTimeSecondHalfStartTime": null,
"status": "first_half" },
"homeScore": 1, "awayScore": 0,
"homeTeam": "Northside FC", "awayTeam": "Coastal United"
},
"logs": [{
"id": "log_7hK2", "timestamp": "2026-09-19T09:41:00.000Z", "elapsedSeconds": 1220,
"timeStr": "20:20", "category": "kmi", "action": "yellow", "detail": "Reckless tackle",
"pathLabels": ["Discipline", "Yellow Card"], "fields": {}, "comment": null,
"rating": null, "targetRole": "center", "targetUserId": "6mK2pQ8xVn3RtJc9LbW1",
"authorName": "A. Coach", "isKMI": true, "commentCount": 0
}],
"as_of": "2026-09-19T09:41:03.000Z",
"cache": { "hit": true, "age_seconds": 12 }
}
}
GET
/api/v1/kmis
kmis:read
▸
Key Match Incidents (KMIs) for a round or a date window: the match, the team and the
official concerned (with their RefReflect id when linked), a link to the footage, the overall
status (pending or marked) and the internal and external marks.
One of round, date/date_from/date_to
or updated_since is required, since there's no "all KMIs" request. A date window may span at
most 62 days. Results are ordered by match date (or by when they last changed, for
updated_since). A page can hold fewer than page_size items while
has_more is true, so keep following next_cursor until it's
false.
| Param | Type | Description |
|---|---|---|
| round | integer | The competition round number (1-200). Only matches that have a round number can match. Round numbers repeat each season, so it's looked up inside the date window you give, or the last 120 days if you give none. If that matches more than 500 fixtures you get a 400: narrow the window. |
| date | date | One match date, YYYY-MM-DD. |
| date_from / date_to | date | Inclusive match-date window, at most 62 days. Give both: a lone date_from or date_to is a 400. |
| updated_since | date-time | ISO 8601. Every KMI whose record or marks changed at or after this instant, oldest change first. Can't be combined with round or the date params. See Sync strategy. |
| competition | string | Exact competition name, case-insensitive. |
| association | string | One associationId. Must be within an association-restricted key's grant, else 403. |
| status | string | pending (no final internal mark yet) or marked. |
| page_size | integer | 1-100, default 50. |
| cursor | string | Opaque pagination token. A cursor only works for the same kind of request (window, round or updated_since) it came from. |
| Field | Meaning |
|---|---|
| id | Stable id of the KMI. |
| status | marked once the final internal mark exists, otherwise pending. |
| type / minute | The on-field decision as logged (yellow, red, penalty_awarded, goal_awarded, offside, etc.) and its match minute. |
| match | id, round (null when the match has no round number), date, competition, division and the two team names. |
| official | The official concerned: userId, name, their role on the match (center, ar1, ar2, fourth or a custom role; null if it can't be resolved) and refReflectUserId (null when not linked). |
| clip | url and timestampSeconds: a link to the footage with a 60-second lead-in. Both null when no footage link is available. |
| coachRating | The coach's own on-the-day rating of the call, as recorded. |
| internalMark | The final internal mark, or null while pending. verdict is correct, incorrect, discussion or no_kmi; decision is what was marked; difficulty is the level from the report format's own scale (its labels vary by format). |
| externalMark | The external review mark, same shape as internalMark, or null when none was recorded. It is separate from the internal mark. |
| updatedAt | When the KMI or either mark last changed. |
{
"data": [{
"id": "k_8fQ2xLm1",
"status": "marked",
"type": "penalty_awarded", "minute": 63,
"match": { "id": "8sZ3xQ1mPn7YkLtRj2Vc", "round": 12, "date": "2026-11-08", "competition": "A-League Men",
"division": null, "homeTeam": "Northside FC", "awayTeam": "Coastal United" },
"team": { "side": "home", "name": "Northside FC" },
"official": { "userId": "6mK2pQ8xVn3RtJc9LbW1", "name": "Casey Centre", "role": "center", "refReflectUserId": 18734 },
"clip": { "url": "https://www.youtube.com/watch?v=abc123XYZ&t=4020s", "timestampSeconds": 4020 },
"coachRating": "support",
"internalMark": { "verdict": "correct", "decision": "Penalty Awarded", "difficulty": "High", "markedAt": "2026-11-10T02:15:00.000Z" },
"externalMark": { "verdict": "incorrect", "decision": "Penalty Awarded", "difficulty": "High", "markedAt": "2026-11-11T06:40:00.000Z" },
"updatedAt": "2026-11-11T06:40:00.000Z"
}],
"pagination": { "page_size": 50, "next_cursor": null, "has_more": false }
}
GET
/api/v1/incidents/{matchId}
incidents:read
▸
A finished match's on-field events: every goal, yellow card, red card, penalty (and how the kick went) and offside, with the minute it happened, the team, the player, and the official it's attributed to. Substitutions and a penalty shoot-out (kick by kick) are included, along with the match's details and final score.
It's only available once full time has been marked. Until then, including while extra
time or a penalty shoot-out is still being played, it answers 409 match_not_full_time.
| Field | Meaning |
|---|---|
| type | goal, yellow_card, red_card, penalty or offside. |
| goal | Goals only. ownGoal and penalty (scored from a penalty kick). A goal's team is the team it counts for on the scoreboard. |
| penaltyKick | Penalties only. result is scored, saved or missed, or null when the outcome wasn't recorded. goalId points at the goal it produced, when one was logged. |
| sanction | Cards only. code is the sanction code when one was logged (Y2, or R7 for a second yellow), reason its wording. null for penalties and offsides. |
| minute / addedMinute | The minute as written on a match report. 12:34 is minute 13; first-half stoppage is minute 45 plus addedMinute. minuteLabel is the same pair as text, e.g. 45+2'. |
| clock | The match clock to the second, as shown in RefWhistle (45+1:32). elapsedSeconds is the raw value. |
| period | first_half, second_half, extra_time_first_half or extra_time_second_half. |
| occurredAt | Wall-clock time of the decision, worked out from the match clock and that half's kick-off. |
| team / player | team.side is home or away. player has the jersey number and, when it's known, the player's name. Either can be null if it wasn't logged. |
| official | The official the decision is attributed to: center, ar1, ar2, fourth, or a custom role such as var. refReflectUserId is their RefReflect id when their account is linked to one, otherwise null. It's on match.officials too. |
| substitutions | Top-level, alongside incidents. Each entry has the team, the team's subNumber (1, 2, 3, and so on), the minute and elapsedSeconds, the playerOn and the playerOff (each with the player's name and shirtNumber). playerOff is null when who went off wasn't recorded. minute is the minute of the change, counted continuously (58 for anything from 58:00 to 58:59), so a first-half stoppage-time substitution reads 46' rather than 45+1'. The whole field is null when substitution data isn't available for the match, for example when no team sheet has been received, and [] when team sheets were received and nobody was substituted. |
| shootout | Top-level, alongside incidents. The penalty shoot-out in the order the kicks were taken: each kick's team, the kick number for that team, the player and whether it was scored or missed, plus the shoot-out score. null when there wasn't one. |
{
"data": {
"match": {
"id": "8sZ3xQ1mPn7YkLtRj2Vc",
"homeTeam": "Northside FC", "homeTeamId": "team_9f3k", "awayTeam": "Coastal United", "awayTeamId": "team_2m7q",
"competition": "NPL Men", "division": "First Grade", "ageGroup": null,
"venue": "Northside Park", "date": "2026-10-18", "time": "15:00", "status": "completed",
"score": { "home": 2, "away": 1, "penalties": null },
"fullTimeAt": "2026-10-18T05:52:10.000Z",
"periods": { "halfLengthMins": 45, "extraTimePlayed": false, "extraTimeHalfLengthMins": null },
"officials": [
{ "role": "center", "userId": "6mK2pQ8xVn3RtJc9LbW1", "name": "Casey Centre", "refReflectUserId": 18734 },
{ "role": "ar1", "userId": "3pL8wQ2nVx7KtRm4JcB5", "name": "Alex Assistant", "refReflectUserId": null }
],
"externalIds": { "dribl_match_id": "1048213", "squadi_match_id": null }
},
"incidents": [{
"id": "log_3pQ9", "type": "penalty", "sanction": null, "goal": null,
"penaltyKick": { "result": "scored", "goalId": "log_4mZ1" },
"period": "first_half", "minute": 21, "addedMinute": null, "minuteLabel": "21'",
"clock": "20:05", "elapsedSeconds": 1205, "occurredAt": "2026-10-18T04:20:05.000Z",
"team": { "side": "home", "name": "Northside FC" }, "player": null,
"official": { "role": "center", "userId": "6mK2pQ8xVn3RtJc9LbW1", "name": "Casey Centre", "refReflectUserId": 18734 }
}, {
"id": "log_4mZ1", "type": "goal", "sanction": null,
"goal": { "ownGoal": false, "penalty": true }, "penaltyKick": null,
"period": "first_half", "minute": 22, "addedMinute": null, "minuteLabel": "22'",
"clock": "21:30", "elapsedSeconds": 1290, "occurredAt": "2026-10-18T04:21:30.000Z",
"team": { "side": "home", "name": "Northside FC" },
"player": { "jerseyNumber": "9", "name": "Sam Striker" },
"official": { "role": "center", "userId": "6mK2pQ8xVn3RtJc9LbW1", "name": "Casey Centre", "refReflectUserId": 18734 }
}, {
"id": "log_7hK2", "type": "yellow_card",
"sanction": { "code": "Y2", "reason": "Dissent", "detail": null }, "goal": null, "penaltyKick": null,
"period": "first_half", "minute": 45, "addedMinute": 2, "minuteLabel": "45+2'",
"clock": "45+1:32", "elapsedSeconds": 2792, "occurredAt": "2026-10-18T04:46:32.000Z",
"team": { "side": "away", "name": "Coastal United" },
"player": { "jerseyNumber": "7", "name": "David Yoo" },
"official": { "role": "center", "userId": "6mK2pQ8xVn3RtJc9LbW1", "name": "Casey Centre", "refReflectUserId": 18734 }
}],
"substitutions": [{
"team": { "side": "home", "name": "Northside FC" }, "subNumber": 1,
"minute": 58, "elapsedSeconds": 3480,
"playerOn": { "name": "Joe Lolley", "shirtNumber": "11" },
"playerOff": { "name": "Max Burgess", "shirtNumber": "7" }
}],
"shootout": null,
"summary": {
"home": { "goals": 2, "yellowCards": 0, "redCards": 0, "penalties": 1, "offsides": 3 },
"away": { "goals": 1, "yellowCards": 1, "redCards": 0, "penalties": 0, "offsides": 2 },
"unassigned": { "goals": 0, "yellowCards": 0, "redCards": 0, "penalties": 0, "offsides": 0 }
}
}
}
"shootout": {
"score": { "home": 4, "away": 3 },
"kicks": [
{ "id": "log_k1", "order": 1, "team": { "side": "home", "name": "Northside FC" }, "kickNumber": 1,
"result": "scored", "player": { "jerseyNumber": "10", "name": null }, "occurredAt": "2026-10-18T06:02:11.000Z" },
{ "id": "log_k2", "order": 2, "team": { "side": "away", "name": "Coastal United" }, "kickNumber": 1,
"result": "missed", "player": { "jerseyNumber": "8", "name": null }, "occurredAt": "2026-10-18T06:02:58.000Z" }
]
}
{ "error": { "code": "match_not_full_time", "message": "Match has not been marked as full time.",
"detail": { "match_id": "8sZ3xQ1mPn7YkLtRj2Vc", "match_status": "live" } } }
GET
/api/v1/openapi.json
unauthenticated
▸
This entire reference, machine-readable, as an OpenAPI 3.1 document. No API key needed, and no rate limit applied. The spec carries no data, so it stays open. It's what drives the explorer, and it's the same document a codegen tool would read to build you a typed client.
Examples
Copy, swap in a real key, run. Every parameter below is a real one from the reference above, nothing invented for the demo.
A basic authenticated request
Either header style works identically.
# Authorization: Bearer
curl https://api.refwhistle.app/api/v1/meta \
-H "Authorization: Bearer refwhistleaB3dE7gH9kLp-xR2kQ9mZpV3sN7wF1cJ6tY8uD0e"
# X-API-Key: no "Bearer" prefix
curl https://api.refwhistle.app/api/v1/meta \
-H "X-API-Key: refwhistleaB3dE7gH9kLp-xR2kQ9mZpV3sN7wF1cJ6tY8uD0e"
A filtered matches list
Live and completed matches in September, for one association, 25 at a time.
curl -G https://api.refwhistle.app/api/v1/matches \
-H "X-API-Key: $REFWHISTLE_KEY" \
--data-urlencode "status=live,completed" \
--data-urlencode "date_from=2026-09-01" \
--data-urlencode "date_to=2026-09-30" \
--data-urlencode "association=assoc_9f3k2m7q1x8p" \
--data-urlencode "page_size=25"
Paginated reports: the cursor round trip
Page one, then feed pagination.next_cursor straight back as ?cursor=. Never decode or construct one yourself. See Sync strategy for why.
curl -G https://api.refwhistle.app/api/v1/reports/published \
-H "X-API-Key: $REFWHISTLE_KEY" \
--data-urlencode "published_since=2026-09-01T00:00:00Z" \
--data-urlencode "page_size=2"
# {"data":[…,…],"pagination":{"page_size":2,
# "next_cursor":"eyJ0ZW5hbnRJZCI6InRlbmFudF93aGlzdGxlX2RlbW8i.4f9a2c…",
# "has_more":true}}
curl -G https://api.refwhistle.app/api/v1/reports/published \
-H "X-API-Key: $REFWHISTLE_KEY" \
--data-urlencode "published_since=2026-09-01T00:00:00Z" \
--data-urlencode "page_size=2" \
--data-urlencode "cursor=eyJ0ZW5hbnRJZCI6InRlbmFudF93aGlzdGxlX2RlbW8i.4f9a2c…"
Polling live coach data
Poll on any interval you like. cache.hit/cache.age_seconds tell you whether you got fresh data or a cached copy.
curl https://api.refwhistle.app/api/v1/coach-data/8sZ3xQ1mPn7YkLtRj2Vc \
-H "X-API-Key: $REFWHISTLE_KEY"
# {"data":{"match":{…},"logs":[…],
# "as_of":"2026-09-19T09:41:03.000Z",
# "cache":{"hit":true,"age_seconds":12}}}
Goals and cards for a referee's match report
Fetch once the match is over. A 409 means full time hasn't been marked yet, so try again later.
curl https://api.refwhistle.app/api/v1/incidents/8sZ3xQ1mPn7YkLtRj2Vc \
-H "X-API-Key: $REFWHISTLE_KEY" \
| jq '.data.incidents[] | select(.type == "goal" or (.type | endswith("_card"))) | [.minuteLabel, .type, .team.name, .player.jerseyNumber, .sanction.code]'
# ["22'","goal","Northside FC","9",null]
# ["45+2'","yellow_card","Coastal United","7","Y2"]
Rate limits
Every key has a per-hour request limit set by RefWhistle (visible via /meta). The window is a fixed UTC clock hour, not a rolling one, so X-RateLimit-Reset is exact, not an estimate.
| Header | On | Meaning |
|---|---|---|
| X-RateLimit-Limit | Every response | The key's configured requests-per-hour ceiling. |
| X-RateLimit-Remaining | Every response | Best-effort estimate of requests left in the current UTC hour. |
| X-RateLimit-Reset | Every response | Unix seconds at the top of the next UTC hour. |
| Retry-After | 429 only | Seconds until the window resets. Safe to sleep on directly. |
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1758279600
Retry-After: 847
{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again after the window resets." } }
Errors
Every non-2xx response, from every endpoint, takes this exact shape:
{ "error": { "code": "invalid_parameter", "message": "'date_from' is invalid.", "detail": { "parameter": "date_from", "received": "last-tuesday" } } }
| Code | HTTP | Meaning |
|---|---|---|
| invalid_parameter | 400 | A query parameter failed validation. detail.parameter names it, and detail.received echoes what you sent. |
| unauthorized | 401 | Missing, malformed, unrecognised, or revoked key. Identical body for all four; nothing to distinguish by response shape. |
| key_expired | 401 | A recognised key past its expiresAt. detail.expired_at carries the date. |
| scope_not_permitted | 403 | The key lacks the scope this route needs. detail.required_scope names it. |
| association_not_permitted | 403 | An association-restricted key requested (or owns a resource in) an association outside its grant. detail.permitted lists what it can see. |
| not_found | 404 | No visible resource at this id. Covers "doesn't exist", "wrong tenant", and (for reports) "not published yet", all identically. |
| match_not_full_time | 409 | /incidents only: the match hasn't been marked as full time yet, or extra time or a shoot-out is still being played. Retry once it has finished. detail.match_status carries the match's status. |
| rate_limited | 429 | Per-hour limit exhausted. See Rate limits. |
| server_error | 500 | Something went wrong on our side. Try again, and contact us if it keeps happening. |
Sync strategy
Five things worth understanding before you write a sync job against this API, not after.
There's no page number, and no total count
Offset pagination gets slower the deeper you page, and a page number drifts when records are added or
changed between requests. So this API never offers ?page=, and a list response never carries a
total/total_pages. Instead, each response includes an opaque
next_cursor that you pass straight back. Walk forward with cursor;
there is no walking backward or jumping ahead, by design.
Reports: poll the status board, then fetch only what's newly published
Don't crawl every report. Poll GET /reports (the last week by
default) on a schedule, compare each sub-report's status with your last poll, and call
/reports/{report_id} only for the ones that have just become published.
If you only want published reports as a stream, use /reports/published: keep the latest
publishedAt you've already processed, and pass it back (minus a minute or two, to absorb clock skew) as
?published_since= next time. Anything with a publishedAt at or after that
value comes back; dedupe by report_id on your side, since the overlap window can hand you
a report you've already seen once.
Matches sync incrementally too, but it's a separate mode, not another filter
The same pattern applies to /matches via ?updated_since=, ordered by
updatedAt instead of publishedAt. Unlike reports, this is a different way of
walking the data, not just another filter, so it can't be combined with
date/date_from/date_to (doing so returns
400 invalid_parameter).
Your first sync against a tenant should be a plain date-window fetch. After that, keep the latest
updatedAt you've seen and pass it back, minus a minute or two for clock skew, as
?updated_since=.
Two things to know. updated_since can't tell you a match was deleted, so run a full
date-window reconcile periodically to catch those. And a match that predates this endpoint and hasn't
changed since won't have an updatedAt yet, so it won't appear via updated_since
until it's next updated. That's why your first sync must be the date-window fetch, not an incremental
one.
/coach-data tells you exactly how fresh it is
Live coaching data is cached for 20 seconds while the match is live and 5 minutes once it's not, so
polling more often than that returns the same data. as_of is the time the data was fetched,
never the current time; cache.hit tells you whether this response came from the cache;
cache.age_seconds is how old the cached copy was. A poller that respects the cache window
gets the freshest data available.
Fetch /incidents after full time, then again if it changes
/incidents/{matchId} opens the moment full time is marked, but coaches can still correct
a log afterwards: the player, the team, or which official it's attributed to. Fetch it once the match is
over, and again before the match report is due, rather than polling during the match. Every call before
full time is a 409 that still counts against your rate limit.
Store ids, not names, and rotation has no grace period
Team names, competition names, and division labels can all be edited in RefWhistle at any time.
matchId, refereeId, coachId, report_id and KMI id are stable,
so key your own database on those, not on display strings. Separately, rotating a key replaces its
secret immediately, with no overlap window. The old secret stops working the instant rotation
completes, the same moment the new one is shown to you. Roll a rotation out atomically in your own
system (update the stored key, don't stage it), and only rotate when you're ready to swap in one step.
Sync KMIs by round or date, then incrementally
Fetch a round (or a date window) from /kmis first. A KMI's marks change after the match, as
marks are recorded, so keep the latest updatedAt you've seen and
pass it back, minus a minute or two for clock skew, as ?updated_since=. Like
/matches, that's its own mode and can't be combined with round or the date params.
Follow next_cursor until has_more is false: a page can come back
short even though more follows. Dedupe on id, since the overlap window can hand you a KMI
you've already seen.
Requesting access
There's no self-serve signup. A RefWhistle system administrator mints your key directly, sets its tenant/association scope, chooses which of the five scopes it carries, and configures its hourly rate limit. Tell us:
- Which RefWhistle tenant (association or league) you're integrating with
- Which of
matches:read/reports:read/coach-data:read/incidents:read/kmis:readyou need - Roughly how many requests per hour you expect to send
- A contact email for the key. This is where partnerName/contactEmail on the key record points