RefWhistleAPI
v1
Overview

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.

https://api.refwhistle.app JSON only Cursor pagination Per-key hourly rate limits

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.

HeaderBearer token
Authorization: Bearer refwhistleaB3dE7gH9kLp-xR2k...
HeaderRaw API key
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.

JSON200 response
{
  "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.

ParamTypeDescription
match_idstring[] multi, max 20Repeat the param or comma-list. Ignores every other filter below.
associationstringOne associationId. Must be within the key's grant, if restricted.
datedateExact match date, YYYY-MM-DD.
date_fromdateInclusive lower bound.
date_todateInclusive upper bound.
statusstring[] multiupcoming · live · completed · canceled
divisionstringFree-text match, 1-200 characters.
competitionstringFree-text match, 1-200 characters.
official_idstringMatches where this user id is an appointed official.
updated_sincedate-timeISO 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_sizeinteger1-100, default 50.
cursorstringOpaque token from a previous pagination.next_cursor.
Response codes
200A page of SerializedMatch objects + pagination.
400invalid_parameter. See detail.parameter.
401unauthorized / key_expired.
403scope_not_permitted / association_not_permitted.
429rate_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.

JSON200 response (abridged)
{
  "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.

JSON200 response (one item, abridged)
{
  "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.

ParamTypeDescription
published_sincedate-timeISO 8601 date or date-time. Inclusive lower bound on publishedAt.
published_untildate-timeSame format. Inclusive upper bound.
referee_idstringReports for one referee.
coach_idstringReports authored by one coach.
match_idstringA single matchId (not a multi/comma-list, unlike /matches's own match_id).
page_sizeinteger1-100, default 50.
cursorstringOpaque token from a previous pagination.next_cursor.
JSON200 response (one item)
{
  "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.

ParamTypeDescription
includestringPass 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.

JSON200 response (abridged)
{
  "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.

ParamTypeDescription
roundintegerThe 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.
datedateOne match date, YYYY-MM-DD.
date_from / date_todateInclusive match-date window, at most 62 days. Give both: a lone date_from or date_to is a 400.
updated_sincedate-timeISO 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.
competitionstringExact competition name, case-insensitive.
associationstringOne associationId. Must be within an association-restricted key's grant, else 403.
statusstringpending (no final internal mark yet) or marked.
page_sizeinteger1-100, default 50.
cursorstringOpaque pagination token. A cursor only works for the same kind of request (window, round or updated_since) it came from.
FieldMeaning
idStable id of the KMI.
statusmarked once the final internal mark exists, otherwise pending.
type / minuteThe on-field decision as logged (yellow, red, penalty_awarded, goal_awarded, offside, etc.) and its match minute.
matchid, round (null when the match has no round number), date, competition, division and the two team names.
officialThe 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).
clipurl and timestampSeconds: a link to the footage with a 60-second lead-in. Both null when no footage link is available.
coachRatingThe coach's own on-the-day rating of the call, as recorded.
internalMarkThe 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).
externalMarkThe external review mark, same shape as internalMark, or null when none was recorded. It is separate from the internal mark.
updatedAtWhen the KMI or either mark last changed.
JSON200 response (one item)
{
  "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.

FieldMeaning
typegoal, yellow_card, red_card, penalty or offside.
goalGoals only. ownGoal and penalty (scored from a penalty kick). A goal's team is the team it counts for on the scoreboard.
penaltyKickPenalties 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.
sanctionCards 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 / addedMinuteThe 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'.
clockThe match clock to the second, as shown in RefWhistle (45+1:32). elapsedSeconds is the raw value.
periodfirst_half, second_half, extra_time_first_half or extra_time_second_half.
occurredAtWall-clock time of the decision, worked out from the match clock and that half's kick-off.
team / playerteam.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.
officialThe 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.
substitutionsTop-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.
shootoutTop-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.
JSON200 response (abridged)
{
  "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 }
    }
  }
}
JSONshootout, when there was one
"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" }
  ]
}
JSON409 before full time
{ "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.

cURLBearer token
# Authorization: Bearer
curl https://api.refwhistle.app/api/v1/meta \
  -H "Authorization: Bearer refwhistleaB3dE7gH9kLp-xR2kQ9mZpV3sN7wF1cJ6tY8uD0e"
cURLX-API-Key
# 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.

cURLGET /matches
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.

cURLPage 1
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}}
cURLPage 2
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.

cURLGET /coach-data/{matchId}
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.

cURLGET /incidents/{matchId}
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.

HeaderOnMeaning
X-RateLimit-LimitEvery responseThe key's configured requests-per-hour ceiling.
X-RateLimit-RemainingEvery responseBest-effort estimate of requests left in the current UTC hour.
X-RateLimit-ResetEvery responseUnix seconds at the top of the next UTC hour.
Retry-After429 onlySeconds until the window resets. Safe to sleep on directly.
HTTP429 rate_limited
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:

JSONError envelope
{ "error": { "code": "invalid_parameter", "message": "'date_from' is invalid.", "detail": { "parameter": "date_from", "received": "last-tuesday" } } }
CodeHTTPMeaning
invalid_parameter400A query parameter failed validation. detail.parameter names it, and detail.received echoes what you sent.
unauthorized401Missing, malformed, unrecognised, or revoked key. Identical body for all four; nothing to distinguish by response shape.
key_expired401A recognised key past its expiresAt. detail.expired_at carries the date.
scope_not_permitted403The key lacks the scope this route needs. detail.required_scope names it.
association_not_permitted403An association-restricted key requested (or owns a resource in) an association outside its grant. detail.permitted lists what it can see.
not_found404No visible resource at this id. Covers "doesn't exist", "wrong tenant", and (for reports) "not published yet", all identically.
match_not_full_time409/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_limited429Per-hour limit exhausted. See Rate limits.
server_error500Something 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.

1

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.

2

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.

3

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.

4

/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.

5

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.

6

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.

7

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:read you 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