{"openapi":"3.1.0","info":{"title":"RefWhistle Public API","version":"1.0.0","description":"A read-only, key-authenticated integration API over RefWhistle's match, coaching-report, and live-coaching data. See https://api.refwhistle.app/docs for the full guide (authentication, worked examples, rate limits, sync strategy).","contact":{"name":"RefWhistle","email":"cameron@refwhistle.app","url":"https://api.refwhistle.app/docs"}},"servers":[{"url":"https://api.refwhistle.app","description":"Production"}],"tags":[{"name":"Matches","description":"Fixtures and their appointment/timing/score data."},{"name":"Reports","description":"Published coaching reports."},{"name":"Coach Data","description":"Live and final per-match coaching timelines."},{"name":"KMIs","description":"Key Match Incidents for a round or date window, with their status and internal/external marks."},{"name":"Incidents","description":"A finished match's goals, cards, penalties, offsides, substitutions and shoot-out."},{"name":"Meta","description":"Key introspection and this specification."}],"paths":{"/api/v1/meta":{"get":{"operationId":"getMeta","summary":"Introspect the current API key","description":"Returns the calling key's own tenant, granted associations, scopes, and rate limit. No scope required beyond a valid key.","tags":["Meta"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"responses":{"200":{"description":"The key's metadata.","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetaResponse"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApiSpec","summary":"The OpenAPI 3.1 document for this API","description":"Returns this OpenAPI 3.1 document. No API key is required and no rate limit is applied.","tags":["Meta"],"security":[],"responses":{"200":{"description":"The OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/matches":{"get":{"operationId":"listMatches","summary":"List matches","description":"Lists matches in the key's tenant. All filters are optional and combined with AND, except match_id: when it is present every other filter is ignored and the matches are looked up by id. updated_since switches to incremental sync (ordered by updatedAt, oldest first) and cannot be combined with date, date_from or date_to.","tags":["Matches"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"parameters":[{"name":"match_id","in":"query","required":false,"description":"Repeat the param or pass a comma-separated list (up to 20 ids). When present, every other filter is ignored and the matches are looked up by id. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"array","items":{"type":"string"},"maxItems":20},"example":["8sZ3xQ1mPn7YkLtRj2Vc","4tR8pW2nKq9XmLb1JhY7"]},{"name":"association","in":"query","required":false,"description":"Restrict to one associationId. On an association-restricted key this must be one of the key's granted associations, otherwise the request returns 403 association_not_permitted. Omit it to search all of the key's granted associations at once. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"assoc_9f3k2m7q1x8p"},{"name":"date","in":"query","required":false,"description":"Exact match date, YYYY-MM-DD.","schema":{"type":"string","format":"date"},"example":"2026-09-26"},{"name":"date_from","in":"query","required":false,"description":"Inclusive lower bound on match date, YYYY-MM-DD.","schema":{"type":"string","format":"date"},"example":"2026-09-01"},{"name":"date_to","in":"query","required":false,"description":"Inclusive upper bound on match date, YYYY-MM-DD.","schema":{"type":"string","format":"date"},"example":"2026-09-30"},{"name":"status","in":"query","required":false,"description":"Repeat the param or pass a comma-separated list.","schema":{"type":"array","items":{"type":"string","enum":["upcoming","live","completed","canceled"]}},"example":["live","completed"]},{"name":"division","in":"query","required":false,"description":"Free-text match, 1-200 characters.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"Premier League"},{"name":"competition","in":"query","required":false,"description":"Free-text match, 1-200 characters.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"NPL Round 24"},{"name":"official_id","in":"query","required":false,"description":"Only matches where this user id is one of the appointed officials. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"6mK2pQ8xVn3RtJc9LbW1"},{"name":"updated_since","in":"query","required":false,"description":"ISO 8601: a date (YYYY-MM-DD) or a full date-time with optional fractional seconds and offset or Z. Switches the list to incremental sync: matches changed at or after this time are returned, ordered by updatedAt with the oldest change first. Cannot be combined with date, date_from or date_to (400 invalid_parameter). Can be combined with association, status, division, competition and official_id. See Sync strategy on the docs page.","schema":{"type":"string"},"example":"2026-09-01T00:00:00Z"},{"name":"page_size","in":"query","required":false,"description":"1-100, default 50.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"cursor","in":"query","required":false,"description":"Opaque pagination token from a previous response's pagination.next_cursor. Pass it back unchanged and do not construct or modify one. See Sync strategy on the docs page for why there is no page-number pagination.","schema":{"type":"string","minLength":1,"maxLength":2000}}],"responses":{"200":{"description":"A page of matches, newest first (date desc, time desc).","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SerializedMatch"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A query parameter failed validation. `detail.parameter` names the offending parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"A query parameter failed validation","value":{"error":{"code":"invalid_parameter","message":"'date_from' is invalid.","detail":{"parameter":"date_from","received":"last-tuesday"}}}}}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"403":{"description":"The API key does not have the scope, or the association access, required for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scope_not_permitted":{"summary":"The key lacks the scope this route requires","value":{"error":{"code":"scope_not_permitted","message":"This API key does not have the 'reports:read' scope.","detail":{"required_scope":"reports:read"}}}},"association_not_permitted":{"summary":"An association-restricted key requested an association outside its grant","value":{"error":{"code":"association_not_permitted","message":"This API key is not permitted to read this association.","detail":{"permitted":["assoc_9f3k2m7q1x8p"]}}}}}}}},"404":{"description":"No resource exists at this id that the key can see. A match/report in a different tenant, or an unpublished report, returns this same 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"summary":"No visible resource at this id","value":{"error":{"code":"not_found","message":"Match not found."}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}},"/api/v1/matches/{matchId}":{"get":{"operationId":"getMatch","summary":"Get one match","description":"A match outside the key's tenant returns 404. A match outside an association-restricted key's grant returns 403 association_not_permitted.","tags":["Matches"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"parameters":[{"name":"matchId","in":"path","required":true,"description":"Matches ^[A-Za-z0-9_~-]{1,128}$. A malformed or unrecognised id returns 404.","schema":{"type":"string"},"example":"8sZ3xQ1mPn7YkLtRj2Vc"}],"responses":{"200":{"description":"The match.","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SerializedMatchDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"403":{"description":"The API key does not have the scope, or the association access, required for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scope_not_permitted":{"summary":"The key lacks the scope this route requires","value":{"error":{"code":"scope_not_permitted","message":"This API key does not have the 'reports:read' scope.","detail":{"required_scope":"reports:read"}}}},"association_not_permitted":{"summary":"An association-restricted key requested an association outside its grant","value":{"error":{"code":"association_not_permitted","message":"This API key is not permitted to read this association.","detail":{"permitted":["assoc_9f3k2m7q1x8p"]}}}}}}}},"404":{"description":"No resource exists at this id that the key can see. A match/report in a different tenant, or an unpublished report, returns this same 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"summary":"No visible resource at this id","value":{"error":{"code":"not_found","message":"Match not found."}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}},"/api/v1/reports":{"get":{"operationId":"listReports","summary":"Reporting status for matches in a date window","description":"One row per match in the window: the match's headline fields, its overall reporting status (submitted, partial, draft or pending) and the status, official and responsible coach for each owed report. Report content is not included. Once a report is published its report_id is returned, which you can pass to GET /reports/{reportId}. Takes the same filters, ordering (date and time, newest first) and cursor as GET /matches. With no date, date_from, date_to or match_id it covers the last 7 days in the tenant's timezone (today and the 6 days before), and the response's window field shows the dates used. updated_since is not supported. Published reports are listed at GET /reports/published. Requires both matches:read and reports:read.","tags":["Reports"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"parameters":[{"name":"match_id","in":"query","required":false,"description":"Repeat the param or pass a comma-separated list (up to 20 ids). When present, every other filter is ignored and the matches are looked up by id. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"array","items":{"type":"string"},"maxItems":20},"example":["8sZ3xQ1mPn7YkLtRj2Vc","4tR8pW2nKq9XmLb1JhY7"]},{"name":"association","in":"query","required":false,"description":"Restrict to one associationId. On an association-restricted key this must be one of the key's granted associations, otherwise the request returns 403 association_not_permitted. Omit it to search all of the key's granted associations at once. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"assoc_9f3k2m7q1x8p"},{"name":"date","in":"query","required":false,"description":"Exact match date, YYYY-MM-DD.","schema":{"type":"string","format":"date"},"example":"2026-09-26"},{"name":"date_from","in":"query","required":false,"description":"Inclusive lower bound on match date, YYYY-MM-DD.","schema":{"type":"string","format":"date"},"example":"2026-09-01"},{"name":"date_to","in":"query","required":false,"description":"Inclusive upper bound on match date, YYYY-MM-DD.","schema":{"type":"string","format":"date"},"example":"2026-09-30"},{"name":"status","in":"query","required":false,"description":"Repeat the param or pass a comma-separated list.","schema":{"type":"array","items":{"type":"string","enum":["upcoming","live","completed","canceled"]}},"example":["live","completed"]},{"name":"division","in":"query","required":false,"description":"Free-text match, 1-200 characters.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"Premier League"},{"name":"competition","in":"query","required":false,"description":"Free-text match, 1-200 characters.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"NPL Round 24"},{"name":"official_id","in":"query","required":false,"description":"Only matches where this user id is one of the appointed officials. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"6mK2pQ8xVn3RtJc9LbW1"},{"name":"page_size","in":"query","required":false,"description":"1-100, default 50.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"cursor","in":"query","required":false,"description":"Opaque pagination token from a previous response's pagination.next_cursor. Pass it back unchanged and do not construct or modify one. See Sync strategy on the docs page for why there is no page-number pagination.","schema":{"type":"string","minLength":1,"maxLength":2000}}],"responses":{"200":{"description":"A page of matches with their reporting status, newest first.","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SerializedMatchReportStatus"}},"window":{"oneOf":[{"type":"null"},{"type":"object","properties":{"date_from":{"oneOf":[{"type":"null"},{"type":"string","format":"date"}]},"date_to":{"oneOf":[{"type":"null"},{"type":"string","format":"date"}]}},"required":["date_from","date_to"],"additionalProperties":false}],"description":"The date window queried. When no date filter is passed this is the last 7 days. null for a match_id lookup."},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","window","pagination"],"additionalProperties":false}}}},"400":{"description":"A query parameter failed validation. `detail.parameter` names the offending parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"A query parameter failed validation","value":{"error":{"code":"invalid_parameter","message":"'date_from' is invalid.","detail":{"parameter":"date_from","received":"last-tuesday"}}}}}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"403":{"description":"The API key does not have the scope, or the association access, required for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scope_not_permitted":{"summary":"The key lacks the scope this route requires","value":{"error":{"code":"scope_not_permitted","message":"This API key does not have the 'reports:read' scope.","detail":{"required_scope":"reports:read"}}}},"association_not_permitted":{"summary":"An association-restricted key requested an association outside its grant","value":{"error":{"code":"association_not_permitted","message":"This API key is not permitted to read this association.","detail":{"permitted":["assoc_9f3k2m7q1x8p"]}}}}}}}},"404":{"description":"No resource exists at this id that the key can see. A match/report in a different tenant, or an unpublished report, returns this same 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"summary":"No visible resource at this id","value":{"error":{"code":"not_found","message":"Match not found."}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}},"/api/v1/reports/published":{"get":{"operationId":"listPublishedReports","summary":"Feed of published coaching reports","description":"Lists published reports in the key's tenant, newest first by publishedAt. Draft reports are never returned. Each report carries its weighted `overallMark` (or null) when the report's format defines one. To poll for what has changed, use GET /reports.","tags":["Reports"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"parameters":[{"name":"published_since","in":"query","required":false,"description":"ISO 8601: a date (YYYY-MM-DD) or a full date-time with optional fractional seconds and offset or Z. Inclusive lower bound on publishedAt.","schema":{"type":"string"},"example":"2026-09-01T00:00:00Z"},{"name":"published_until","in":"query","required":false,"description":"Same format as published_since. Inclusive upper bound on publishedAt.","schema":{"type":"string"},"example":"2026-09-30T23:59:59Z"},{"name":"referee_id","in":"query","required":false,"description":"Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"4tR8pW2nKq9XmLb1JhY7"},{"name":"coach_id","in":"query","required":false,"description":"Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"9jH4kR7wLp2VnQm8TfB3"},{"name":"match_id","in":"query","required":false,"description":"A single matchId. Unlike match_id on /matches, this does not accept a list. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"8sZ3xQ1mPn7YkLtRj2Vc"},{"name":"association","in":"query","required":false,"description":"Restrict to one associationId. On an association-restricted key this must be one of the key's granted associations, otherwise the request returns 403 association_not_permitted. Omit it to search all of the key's granted associations at once. Reports with no associationId recorded do not match this filter or an association-restricted key's grant. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"assoc_9f3k2m7q1x8p"},{"name":"page_size","in":"query","required":false,"description":"1-100, default 50.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"cursor","in":"query","required":false,"description":"Opaque pagination token from a previous response's pagination.next_cursor. Pass it back unchanged and do not construct or modify one. See Sync strategy on the docs page for why there is no page-number pagination.","schema":{"type":"string","minLength":1,"maxLength":2000}}],"responses":{"200":{"description":"A page of published reports.","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SerializedReportSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A query parameter failed validation. `detail.parameter` names the offending parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"A query parameter failed validation","value":{"error":{"code":"invalid_parameter","message":"'date_from' is invalid.","detail":{"parameter":"date_from","received":"last-tuesday"}}}}}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"403":{"description":"The API key does not have the scope, or the association access, required for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scope_not_permitted":{"summary":"The key lacks the scope this route requires","value":{"error":{"code":"scope_not_permitted","message":"This API key does not have the 'reports:read' scope.","detail":{"required_scope":"reports:read"}}}},"association_not_permitted":{"summary":"An association-restricted key requested an association outside its grant","value":{"error":{"code":"association_not_permitted","message":"This API key is not permitted to read this association.","detail":{"permitted":["assoc_9f3k2m7q1x8p"]}}}}}}}},"404":{"description":"No resource exists at this id that the key can see. A match/report in a different tenant, or an unpublished report, returns this same 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"summary":"No visible resource at this id","value":{"error":{"code":"not_found","message":"Match not found."}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}},"/api/v1/reports/{reportId}":{"get":{"operationId":"getReport","summary":"Get one published report","description":"Includes the weighted `overallMark` (value, outOf, label, status, scheme and a per-section breakdown) when the report's format defines one, otherwise null. A report that does not exist, belongs to another tenant or is not yet published returns 404. A published report in the same tenant that is outside an association-restricted key's grants (including one with no association recorded) returns 403 association_not_permitted.","tags":["Reports"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"parameters":[{"name":"reportId","in":"path","required":true,"description":"Report id in the form '{matchId}~{refereeId}', as returned in report_id by the list endpoints. A malformed id returns 404.","schema":{"type":"string"},"example":"8sZ3xQ1mPn7YkLtRj2Vc~4tR8pW2nKq9XmLb1JhY7"},{"name":"include","in":"query","required":false,"description":"Pass 'snapshots' to also include gradingSpecSnapshot and blueprintSnapshot in the response. Any other value, or omitting the param, excludes them. This parameter never returns 400 invalid_parameter.","schema":{"type":"string","enum":["snapshots"]},"example":"snapshots"}],"responses":{"200":{"description":"The report.","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SerializedReportDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"403":{"description":"The API key does not have the scope, or the association access, required for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scope_not_permitted":{"summary":"The key lacks the scope this route requires","value":{"error":{"code":"scope_not_permitted","message":"This API key does not have the 'reports:read' scope.","detail":{"required_scope":"reports:read"}}}},"association_not_permitted":{"summary":"An association-restricted key requested an association outside its grant","value":{"error":{"code":"association_not_permitted","message":"This API key is not permitted to read this association.","detail":{"permitted":["assoc_9f3k2m7q1x8p"]}}}}}}}},"404":{"description":"No resource exists at this id that the key can see. A match/report in a different tenant, or an unpublished report, returns this same 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"summary":"No visible resource at this id","value":{"error":{"code":"not_found","message":"Match not found."}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}},"/api/v1/coach-data/{matchId}":{"get":{"operationId":"getCoachData","summary":"Live/final coaching timeline for one match","description":"All logs for the match plus a compact match state. Responses are cached for 20 seconds while the match is live and 5 minutes otherwise. The as_of and cache fields show how fresh the data is, so polling more often than that returns the same data. A match in another tenant returns 404. A match in the same tenant that is outside an association-restricted key's grants returns 403 association_not_permitted.","tags":["Coach Data"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"parameters":[{"name":"matchId","in":"path","required":true,"description":"Matches ^[A-Za-z0-9_~-]{1,128}$. A malformed or unrecognised id returns 404.","schema":{"type":"string"},"example":"8sZ3xQ1mPn7YkLtRj2Vc"}],"responses":{"200":{"description":"The match's live/final coaching data.","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CoachDataResponse"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"403":{"description":"The API key does not have the scope, or the association access, required for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scope_not_permitted":{"summary":"The key lacks the scope this route requires","value":{"error":{"code":"scope_not_permitted","message":"This API key does not have the 'reports:read' scope.","detail":{"required_scope":"reports:read"}}}},"association_not_permitted":{"summary":"An association-restricted key requested an association outside its grant","value":{"error":{"code":"association_not_permitted","message":"This API key is not permitted to read this association.","detail":{"permitted":["assoc_9f3k2m7q1x8p"]}}}}}}}},"404":{"description":"No resource exists at this id that the key can see. A match/report in a different tenant, or an unpublished report, returns this same 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"summary":"No visible resource at this id","value":{"error":{"code":"not_found","message":"Match not found."}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}},"/api/v1/kmis":{"get":{"operationId":"listKmis","summary":"Key Match Incidents for a round or date window, with their marks","description":"Key Match Incidents (KMIs) with their match, the official concerned (and 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`, a `date_from` and `date_to` pair (at most 62 days) or `updated_since` is required; `date_from` and `date_to` must be given together. Ordered by match date, or by last change when using `updated_since`. A page can hold fewer than `page_size` items while `has_more` is true, so keep following `next_cursor` until it is false. Requires the kmis:read scope.","tags":["KMIs"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"parameters":[{"name":"round","in":"query","required":false,"description":"The competition round number (1-200). Only matches that have a round number can match. Round numbers repeat every season, so the round is looked up inside the date window given, or the last 120 days when none is. Cannot be combined with updated_since.","schema":{"type":"integer","minimum":1,"maximum":200},"example":12},{"name":"date","in":"query","required":false,"description":"Exact match date, YYYY-MM-DD.","schema":{"type":"string","format":"date"},"example":"2026-09-26"},{"name":"date_from","in":"query","required":false,"description":"Inclusive start of the match-date window, YYYY-MM-DD. Must be given together with date_to; the window may span at most 62 days.","schema":{"type":"string","format":"date"},"example":"2026-11-07"},{"name":"date_to","in":"query","required":false,"description":"Inclusive end of the match-date window, YYYY-MM-DD. Must be given together with date_from.","schema":{"type":"string","format":"date"},"example":"2026-11-09"},{"name":"updated_since","in":"query","required":false,"description":"ISO 8601. Incremental sync: every KMI whose record or marks changed at or after this instant, oldest change first. Cannot be combined with date, date_from, date_to or round (400 invalid_parameter).","schema":{"type":"string"},"example":"2026-11-09T00:00:00Z"},{"name":"competition","in":"query","required":false,"description":"Free-text match, 1-200 characters.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"NPL Round 24"},{"name":"association","in":"query","required":false,"description":"Restrict to one associationId. On an association-restricted key this must be one of the key's granted associations, otherwise the request returns 403 association_not_permitted. Omit it to search all of the key's granted associations at once. Matches ^[A-Za-z0-9_~-]{1,128}$.","schema":{"type":"string"},"example":"assoc_9f3k2m7q1x8p"},{"name":"status","in":"query","required":false,"description":"`pending` (no final internal mark yet) or `marked`.","schema":{"type":"string","enum":["pending","marked"]}},{"name":"page_size","in":"query","required":false,"description":"1-100, default 50.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50},{"name":"cursor","in":"query","required":false,"description":"Opaque pagination token from a previous response's pagination.next_cursor. Pass it back unchanged and do not construct or modify one. See Sync strategy on the docs page for why there is no page-number pagination.","schema":{"type":"string","minLength":1,"maxLength":2000}}],"responses":{"200":{"description":"A page of KMIs.","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SerializedKmi"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false}}}},"400":{"description":"A query parameter failed validation. `detail.parameter` names the offending parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"A query parameter failed validation","value":{"error":{"code":"invalid_parameter","message":"'date_from' is invalid.","detail":{"parameter":"date_from","received":"last-tuesday"}}}}}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"403":{"description":"The API key does not have the scope, or the association access, required for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scope_not_permitted":{"summary":"The key lacks the scope this route requires","value":{"error":{"code":"scope_not_permitted","message":"This API key does not have the 'reports:read' scope.","detail":{"required_scope":"reports:read"}}}},"association_not_permitted":{"summary":"An association-restricted key requested an association outside its grant","value":{"error":{"code":"association_not_permitted","message":"This API key is not permitted to read this association.","detail":{"permitted":["assoc_9f3k2m7q1x8p"]}}}}}}}},"404":{"description":"No resource exists at this id that the key can see. A match/report in a different tenant, or an unpublished report, returns this same 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"summary":"No visible resource at this id","value":{"error":{"code":"not_found","message":"Match not found."}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}},"/api/v1/incidents/{matchId}":{"get":{"operationId":"getMatchIncidents","summary":"A finished match's goals, cards, penalties and offsides","description":"The on-field events of one match: goals, yellow cards, red cards, penalties (and how the kick went) and offsides, each with the minute, period, team, player and the official it is attributed to. Also returns substitutions, the penalty shoot-out kick by kick, the match's details and the final score. Only available once full time has been marked; before that it returns 409 match_not_full_time. A match in another tenant returns 404. A match in the same tenant that is outside an association-restricted key's grants returns 403 association_not_permitted. Requires the incidents:read scope.","tags":["Incidents"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"parameters":[{"name":"matchId","in":"path","required":true,"description":"Matches ^[A-Za-z0-9_~-]{1,128}$. A malformed or unrecognised id returns 404.","schema":{"type":"string"},"example":"8sZ3xQ1mPn7YkLtRj2Vc"}],"responses":{"200":{"description":"The match's decisions and details.","headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MatchIncidentsResponse"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, malformed, unrecognised, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthorized":{"summary":"Missing, malformed, unrecognised, or revoked key","value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}},"key_expired":{"summary":"A recognised key past its expiresAt","value":{"error":{"code":"key_expired","message":"This API key has expired.","detail":{"expired_at":"2026-06-01T00:00:00.000Z"}}}}}}}},"403":{"description":"The API key does not have the scope, or the association access, required for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scope_not_permitted":{"summary":"The key lacks the scope this route requires","value":{"error":{"code":"scope_not_permitted","message":"This API key does not have the 'reports:read' scope.","detail":{"required_scope":"reports:read"}}}},"association_not_permitted":{"summary":"An association-restricted key requested an association outside its grant","value":{"error":{"code":"association_not_permitted","message":"This API key is not permitted to read this association.","detail":{"permitted":["assoc_9f3k2m7q1x8p"]}}}}}}}},"404":{"description":"No resource exists at this id that the key can see. A match/report in a different tenant, or an unpublished report, returns this same 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"summary":"No visible resource at this id","value":{"error":{"code":"not_found","message":"Match not found."}}}}}}},"409":{"description":"The match has not been marked as full time yet, so its incidents are not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"match_not_full_time":{"summary":"The match is not finished","value":{"error":{"code":"match_not_full_time","message":"Match has not been marked as full time.","detail":{"match_id":"8sZ3xQ1mPn7YkLtRj2Vc","match_status":"live"}}}}}}}},"429":{"description":"The key's per-hour rate limit has been exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"Rate limit exceeded","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again after the window resets."}}}}}},"headers":{"X-RateLimit-Limit":{"description":"The key's configured requests-per-hour limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Estimated requests remaining in the current UTC-hour window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at the top of the next UTC hour, when the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the current UTC-hour window resets. Only present on 429 responses.","schema":{"type":"integer"}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"error":{"code":"server_error","message":"Something went wrong. Please try again."}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"refwhistle<keyId>-<secret>","description":"Authorization: Bearer refwhistle<keyId>-<secret>"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"X-API-Key: refwhistle<keyId>-<secret> (no 'Bearer ' prefix)."}},"schemas":{"SerializedMatch":{"type":"object","properties":{"id":{"type":"string","description":"The match id.","example":"8sZ3xQ1mPn7YkLtRj2Vc"},"homeTeam":{"type":["string","null"]},"homeTeamId":{"type":["string","null"]},"awayTeam":{"type":["string","null"]},"awayTeamId":{"type":["string","null"]},"venue":{"type":["string","null"]},"date":{"type":["string","null"],"description":"YYYY-MM-DD.","example":"2026-09-26"},"time":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["upcoming","live","completed","canceled",null]},"competition":{"type":["string","null"]},"division":{"type":["string","null"]},"ageGroup":{"type":["string","null"]},"level":{"type":["string","null"]},"league_name":{"type":["string","null"]},"associationId":{"type":["string","null"]},"sport":{"type":"string","description":"The sport for this match, e.g. 'football' or 'futsal'. Defaults to 'football'.","example":"football"},"homeScore":{"type":["number","null"]},"awayScore":{"type":["number","null"]},"isReported":{"type":"boolean"},"appointments":{"type":"object","description":"Keyed by role: 'center', 'ar1', 'ar2', 'fourth', 'coach', 'refereeCoach', or 'extra:<roleId>' for a custom role. A role with no appointment, or whose appointee cannot be resolved, is absent.","additionalProperties":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"refReflectUserId":{"type":["integer","null"],"description":"The official's RefReflect id when their account is linked to one; null otherwise.","example":18734}},"required":["userId","name","refReflectUserId"],"additionalProperties":false}},"timing":{"type":"object","properties":{"status":{"type":["string","null"]},"halfLengthMins":{"type":["number","null"]},"periods":{"type":"object","description":"The sport's period structure, for example 2 x 45 minutes plus 2 x 15 minutes of extra time for football, or 2 x 20 plus 2 x 5 for futsal. `extraTime` is null for a sport with no extra time. `halfLengthMins` is also provided.","properties":{"count":{"type":"number","example":2},"lengthMins":{"type":"number","example":45},"label":{"type":"string","example":"Half"},"extraTime":{"anyOf":[{"type":"object","properties":{"count":{"type":"number","example":2},"lengthMins":{"type":"number","example":15}},"required":["count","lengthMins"],"additionalProperties":false},{"type":"null"}]}},"required":["count","lengthMins","label","extraTime"],"additionalProperties":false},"extraTimeEnabled":{"type":"boolean"}},"required":["status","halfLengthMins","periods","extraTimeEnabled"],"additionalProperties":false},"dribl_match_id":{"type":["string","null"]},"squadi_match_id":{"type":["string","null"]},"opta_fixture_uuid":{"type":["string","null"]},"home_logo":{"type":["string","null"],"description":"Club logo URL, when available."},"away_logo":{"type":["string","null"],"description":"Club logo URL, when available."},"updatedAt":{"type":["string","null"],"description":"ISO 8601 time the match last changed. Null for a match that has not changed since this field was introduced. Use the latest value you have seen as your next updated_since. See Sync strategy on the docs page.","example":"2026-09-19T22:14:03.000Z"}},"required":["id","homeTeam","homeTeamId","awayTeam","awayTeamId","venue","date","time","status","competition","division","ageGroup","level","league_name","associationId","sport","homeScore","awayScore","isReported","appointments","timing","dribl_match_id","squadi_match_id","opta_fixture_uuid","home_logo","away_logo","updatedAt"],"additionalProperties":false},"SerializedMatchDetail":{"allOf":[{"$ref":"#/components/schemas/SerializedMatch"},{"type":"object","properties":{"videoUrl":{"type":["string","null"]},"streamCalibration":{"oneOf":[{"type":"null"},{"type":"object","properties":{"youtubeUrl":{"type":["string","null"]}},"required":["youtubeUrl"],"additionalProperties":false}]}},"required":["videoUrl","streamCalibration"]}]},"SerializedLiveLog":{"type":"object","properties":{"id":{"type":["string","null"]},"timestamp":{"type":["string","null"],"format":"date-time"},"clientTimestamp":{"type":["string","null"],"format":"date-time"},"elapsedSeconds":{"type":["number","null"]},"timeStr":{"type":["string","null"]},"category":{"type":["string","null"]},"action":{"type":["string","null"]},"detail":{"type":["string","null"]},"pathLabels":{"type":"array","items":{"type":"string"}},"fields":{"type":"object","description":"Answers captured for this log, keyed by field id. The shape varies by report format.","additionalProperties":true},"comment":{"type":["string","null"]},"rating":{"type":["string","null"]},"targetRole":{"type":["string","null"],"description":"The role-tab id (e.g. 'center', 'ar1') this log was captured under."},"targetUserId":{"type":["string","null"]},"authorName":{"type":["string","null"]},"isKMI":{"type":"boolean","description":"Whether this log is a Key Match Incident."},"commentCount":{"type":["number","null"]}},"required":["id","timestamp","clientTimestamp","elapsedSeconds","timeStr","category","action","detail","pathLabels","fields","comment","rating","targetRole","targetUserId","authorName","isKMI","commentCount"],"additionalProperties":false},"SerializedOverallMark":{"type":"object","description":"The report's weighted overall mark. Set only when the report's format has an overall-mark scheme for this match and role (never for the 4th Official); null otherwise. Available to any key with reports:read.","properties":{"value":{"type":["number","null"],"description":"The mark out of `outOf`, full precision (round for display). Null when status is 'incomplete'.","example":75.28},"outOf":{"type":"number","description":"The total the weighted sections contribute to (e.g. 100).","example":100},"label":{"type":"string","description":"The format's name for the mark.","example":"Overall Mark"},"status":{"type":"string","enum":["complete","incomplete"],"description":"'incomplete' means a weighted section is still ungraded, so there is no value yet. Sections graded N/A are dropped and the rest re-weighted."},"scheme":{"type":["string","null"],"description":"The weighting scheme applied (resolved from the match's competition/association).","example":"ALM 2026/27"},"breakdown":{"type":"array","description":"One row per weighted section.","items":{"type":"object","properties":{"section":{"type":"string","example":"Application of Law"},"grade":{"type":["string","null"],"description":"The grade picked for the section; null when ungraded.","example":"Above Average"},"weight":{"type":["number","null"],"description":"The section's share of the total, 0..1. Null for an ungraded or N/A section.","example":0.2392},"points":{"type":["number","null"],"description":"Points the section contributed out of `outOf`. Null for an ungraded or N/A section.","example":21.93}},"required":["section","grade","weight","points"],"additionalProperties":false}}},"required":["value","outOf","label","status","scheme","breakdown"],"additionalProperties":false},"SerializedReportSummary":{"type":"object","properties":{"report_id":{"type":"string","description":"Composite public id: '{matchId}~{refereeId}'. Use this exact value with GET /reports/{reportId}.","example":"8sZ3xQ1mPn7YkLtRj2Vc~4tR8pW2nKq9XmLb1JhY"},"matchId":{"type":["string","null"]},"refereeId":{"type":["string","null"]},"refReflectUserId":{"type":["integer","null"],"description":"The official's RefReflect id when their account is linked to one; null otherwise.","example":18734},"coachId":{"type":["string","null"]},"officialType":{"type":["string","null"]},"publishedAt":{"type":["string","null"],"format":"date-time"},"reportFormatId":{"type":["string","null"]},"summary":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":true}],"description":"A summary of the report. The shape depends on the report's format."},"overallMark":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SerializedOverallMark"}],"description":"The weighted overall mark, or null when this report has none."}},"required":["report_id","matchId","refereeId","refReflectUserId","coachId","officialType","publishedAt","reportFormatId","summary","overallMark"],"additionalProperties":false},"SerializedReportDetail":{"allOf":[{"$ref":"#/components/schemas/SerializedReportSummary"},{"type":"object","properties":{"narratives":{"type":"object","additionalProperties":{"type":"string"}},"kpiAnswers":{"type":"object","additionalProperties":{"enum":["yes","no",null]}},"profileMarks":{"type":"object","additionalProperties":{"enum":["strength","improvement",null]}},"overallCoachingComments":{"type":["string","null"]},"finalSummary":{"type":["string","null"]},"values":{"type":"object","description":"The report's answers, keyed by block id. The shape depends on the report's format.","additionalProperties":true},"logs":{"type":"array","items":{"$ref":"#/components/schemas/SerializedLiveLog"}},"videoUrl":{"type":["string","null"]},"refereeResponse":{"oneOf":[{"type":"null"},{"type":"object","properties":{"acknowledgedAt":{"type":"string","format":"date-time"},"values":{"type":"object","additionalProperties":true},"reflectionSubmittedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}]},"formatVersion":{"type":["number","null"],"description":"Version of the report format when the report was captured and published. Needed to interpret 'values' and log 'fields' for a custom format."},"gradingSpecSnapshot":{"description":"Frozen grading spec at publish time. Only present when the request included '?include=snapshots'."},"blueprintSnapshot":{"description":"Frozen report blueprint at publish time. Only present when the request included '?include=snapshots'."}},"required":["narratives","kpiAnswers","profileMarks","overallCoachingComments","finalSummary","values","logs","videoUrl","refereeResponse","formatVersion"]}]},"SerializedMatchReportStatus":{"type":"object","properties":{"match":{"type":"object","properties":{"id":{"type":"string"},"homeTeam":{"type":["string","null"]},"homeTeamId":{"type":["string","null"]},"awayTeam":{"type":["string","null"]},"awayTeamId":{"type":["string","null"]},"date":{"type":["string","null"],"description":"YYYY-MM-DD, tenant-local."},"time":{"type":["string","null"],"description":"Kick-off, HH:mm, tenant-local."},"venue":{"type":["string","null"]},"competition":{"type":["string","null"]},"division":{"type":["string","null"]},"level":{"type":["string","null"]},"associationId":{"type":["string","null"]},"status":{"type":["string","null"]}},"required":["id","homeTeam","homeTeamId","awayTeam","awayTeamId","date","time","venue","competition","division","level","associationId","status"],"additionalProperties":false},"reportingStatus":{"type":"string","enum":["submitted","partial","draft","pending"],"description":"submitted: every owed report is published. partial: at least one is published. draft: none are published but at least one is drafted. pending: nothing has been started."},"counts":{"type":"object","properties":{"required":{"type":"integer"},"published":{"type":"integer","description":"Owed reports that are published."},"draft":{"type":"integer"},"outstanding":{"type":"integer","description":"Owed reports not yet published (drafts count as outstanding)."}},"required":["required","published","draft","outstanding"],"additionalProperties":false},"coach":{"oneOf":[{"type":"null"},{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":["string","null"]}},"required":["userId","name"],"additionalProperties":false}],"description":"The match coach."},"reports":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","description":"center, ar1, ar2, fourth, var or avar."},"required":{"type":"boolean","description":"Whether this report is owed on the match. A report written for a role that isn't owed is still listed, with required: false."},"status":{"type":"string","enum":["published","draft","missing"]},"official":{"oneOf":[{"type":"null"},{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":["string","null"]}},"required":["userId","name"],"additionalProperties":false}],"description":"The official the report is about."},"coach":{"oneOf":[{"type":"null"},{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":["string","null"]}},"required":["userId","name"],"additionalProperties":false}],"description":"Who owes the report: the position's report author (e.g. a VAR coach) when one is appointed, else the match coach."},"report_id":{"type":["string","null"],"description":"Set only once published. Pass it to GET /reports/{reportId} for the content."},"publishedAt":{"type":["string","null"],"format":"date-time"},"lastActivityAt":{"type":["string","null"],"format":"date-time","description":"Latest save or publish of this report."}},"required":["role","required","status","official","coach","report_id","publishedAt","lastActivityAt"],"additionalProperties":false}},"lastActivityAt":{"type":["string","null"],"format":"date-time","description":"Latest save or publish across this match's reports. Compare it between polls to spot changes."}},"required":["match","reportingStatus","counts","coach","reports","lastActivityAt"],"additionalProperties":false},"SerializedCoachDataMatch":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":["string","null"]},"timing":{"oneOf":[{"type":"null"},{"type":"object","properties":{"firstHalfStartTime":{"type":["number","null"]},"secondHalfStartTime":{"type":["number","null"]},"extraTimeFirstHalfStartTime":{"type":["number","null"]},"extraTimeSecondHalfStartTime":{"type":["number","null"]},"suspensions":{"type":"array","description":"Play suspensions (e.g. a weather delay mid-half): the match clock is frozen from startAt to endAt (epoch ms; endAt null = still suspended). Subtract them from a period's elapsed time.","items":{"type":"object","properties":{"startAt":{"type":"number"},"endAt":{"type":["number","null"]}},"required":["startAt","endAt"],"additionalProperties":false}},"status":{"type":["string","null"]}},"required":["firstHalfStartTime","secondHalfStartTime","extraTimeFirstHalfStartTime","extraTimeSecondHalfStartTime","suspensions","status"],"additionalProperties":false}]},"homeScore":{"type":["number","null"]},"awayScore":{"type":["number","null"]},"homeTeam":{"type":["string","null"]},"awayTeam":{"type":["string","null"]}},"required":["id","status","timing","homeScore","awayScore","homeTeam","awayTeam"],"additionalProperties":false},"CoachDataResponse":{"type":"object","properties":{"match":{"$ref":"#/components/schemas/SerializedCoachDataMatch"},"logs":{"type":"array","items":{"$ref":"#/components/schemas/SerializedLiveLog"}},"as_of":{"type":"string","format":"date-time","description":"When this data was fetched. On a cache hit this is the original fetch time, never the current time."},"cache":{"type":"object","properties":{"hit":{"type":"boolean"},"age_seconds":{"type":"number","description":"0 on a fresh fetch; real elapsed seconds since fetch on a cache hit."}},"required":["hit","age_seconds"],"additionalProperties":false}},"required":["match","logs","as_of","cache"],"additionalProperties":false},"SerializedIncident":{"type":"object","properties":{"id":{"type":"string","description":"Stable id of the decision. Unique within the match."},"type":{"type":"string","enum":["goal","yellow_card","red_card","penalty","offside"]},"sanction":{"oneOf":[{"type":"null"},{"type":"object","description":"Cards only. `code` is the sanction code when the card was logged with one (e.g. 'Y2', 'R7' for a second yellow).","properties":{"code":{"type":["string","null"],"example":"Y2"},"reason":{"type":["string","null"],"example":"Dissent"},"detail":{"type":["string","null"]}},"required":["code","reason","detail"],"additionalProperties":false}]},"goal":{"oneOf":[{"type":"null"},{"type":"object","description":"Goals only. `team` on a goal is the team it counts for on the scoreboard.","properties":{"ownGoal":{"type":"boolean"},"penalty":{"type":"boolean","description":"Scored from a penalty kick."}},"required":["ownGoal","penalty"],"additionalProperties":false}]},"penaltyKick":{"oneOf":[{"type":"null"},{"type":"object","description":"Penalties only. How the kick went. `result` is null when the outcome wasn't recorded.","properties":{"result":{"type":["string","null"],"enum":["scored","saved","missed",null]},"goalId":{"type":["string","null"],"description":"The `id` of the goal this penalty produced, when it was logged."}},"required":["result","goalId"],"additionalProperties":false}]},"period":{"type":"string","enum":["first_half","second_half","extra_time_first_half","extra_time_second_half"]},"minute":{"type":"integer","description":"The minute being played, as written on a match report: 13 for 12:34; 45 for any first-half stoppage.","example":45},"addedMinute":{"type":["integer","null"],"description":"Stoppage-time minute on top of `minute` (2 for 45+2'); null inside regulation time.","example":2},"minuteLabel":{"type":"string","example":"45+2'"},"clock":{"type":"string","description":"The match clock to the second, as shown in RefWhistle: '12:34', '45+1:32'.","example":"45+1:32"},"elapsedSeconds":{"type":"integer","description":"Raw continuous match clock in seconds (the 2nd half starts at 2700 for 45-minute halves)."},"occurredAt":{"type":["string","null"],"format":"date-time","description":"Wall-clock time of the decision, from the match clock and the half's kick-off time."},"team":{"oneOf":[{"type":"null"},{"type":"object","properties":{"side":{"type":"string","enum":["home","away"]},"name":{"type":["string","null"]}},"required":["side","name"],"additionalProperties":false}]},"player":{"oneOf":[{"type":"null"},{"type":"object","properties":{"jerseyNumber":{"type":["string","null"],"example":"7"},"name":{"type":["string","null"]}},"required":["jerseyNumber","name"],"additionalProperties":false}]},"official":{"type":"object","properties":{"role":{"type":"string","description":"The official's position: 'center', 'ar1', 'ar2', 'fourth', or a custom role id such as 'var'.","example":"center"},"userId":{"type":["string","null"]},"name":{"type":["string","null"]},"refReflectUserId":{"type":["integer","null"],"description":"The official's RefReflect id when their account is linked to one; null otherwise.","example":18734}},"required":["role","userId","name","refReflectUserId"],"additionalProperties":false,"description":"The official the decision is attributed to."}},"required":["id","type","sanction","goal","penaltyKick","period","minute","addedMinute","minuteLabel","clock","elapsedSeconds","occurredAt","team","player","official"],"additionalProperties":false},"SerializedIncidentsMatch":{"type":"object","properties":{"id":{"type":"string"},"homeTeam":{"type":["string","null"]},"homeTeamId":{"type":["string","null"]},"awayTeam":{"type":["string","null"]},"awayTeamId":{"type":["string","null"]},"competition":{"type":["string","null"]},"division":{"type":["string","null"]},"ageGroup":{"type":["string","null"]},"venue":{"type":["string","null"]},"date":{"type":["string","null"],"description":"YYYY-MM-DD, the association's local date."},"time":{"type":["string","null"],"description":"HH:mm kick-off, the association's local time."},"status":{"type":["string","null"]},"score":{"type":"object","properties":{"home":{"type":["number","null"]},"away":{"type":["number","null"]},"penalties":{"oneOf":[{"type":"null"},{"type":"object","description":"Penalty shoot-out score, when there was one.","properties":{"home":{"type":["number","null"]},"away":{"type":["number","null"]}},"required":["home","away"],"additionalProperties":false}]}},"required":["home","away","penalties"],"additionalProperties":false},"fullTimeAt":{"type":["string","null"],"format":"date-time","description":"When full time was marked."},"periods":{"type":"object","properties":{"halfLengthMins":{"type":"number","example":45},"extraTimePlayed":{"type":"boolean"},"extraTimeHalfLengthMins":{"type":["number","null"]}},"required":["halfLengthMins","extraTimePlayed","extraTimeHalfLengthMins"],"additionalProperties":false},"officials":{"type":"array","description":"The appointed referee, assistants and fourth official, plus any other official a decision is attributed to (e.g. a VAR). Coaches and analysts are never listed.","items":{"type":"object","properties":{"role":{"type":"string","description":"The official's position: 'center', 'ar1', 'ar2', 'fourth', or a custom role id such as 'var'.","example":"center"},"userId":{"type":["string","null"]},"name":{"type":["string","null"]},"refReflectUserId":{"type":["integer","null"],"description":"The official's RefReflect id when their account is linked to one; null otherwise.","example":18734}},"required":["role","userId","name","refReflectUserId"],"additionalProperties":false}},"externalIds":{"type":"object","properties":{"dribl_match_id":{"type":["string","null"]},"squadi_match_id":{"type":["string","null"]}},"required":["dribl_match_id","squadi_match_id"],"additionalProperties":false}},"required":["id","homeTeam","homeTeamId","awayTeam","awayTeamId","competition","division","ageGroup","venue","date","time","status","score","fullTimeAt","periods","officials","externalIds"],"additionalProperties":false},"SerializedShootout":{"type":"object","properties":{"score":{"type":"object","description":"Counted from the kicks.","properties":{"home":{"type":"integer"},"away":{"type":"integer"}},"required":["home","away"],"additionalProperties":false},"kicks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"order":{"type":"integer","description":"1-based order the kicks were taken in, across both teams."},"team":{"oneOf":[{"type":"null"},{"type":"object","properties":{"side":{"type":"string","enum":["home","away"]},"name":{"type":["string","null"]}},"required":["side","name"],"additionalProperties":false}]},"kickNumber":{"type":["integer","null"],"description":"The kick's number for its own team (1-5, then sudden death)."},"result":{"type":"string","enum":["scored","missed"]},"player":{"oneOf":[{"type":"null"},{"type":"object","properties":{"jerseyNumber":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["jerseyNumber","name"],"additionalProperties":false}]},"occurredAt":{"type":["string","null"],"format":"date-time"}},"required":["id","order","team","kickNumber","result","player","occurredAt"],"additionalProperties":false}}},"required":["score","kicks"],"additionalProperties":false},"SerializedSubstitution":{"type":"object","properties":{"team":{"type":"object","properties":{"side":{"type":"string","enum":["home","away"]},"name":{"type":["string","null"]}},"required":["side","name"],"additionalProperties":false},"subNumber":{"type":"integer","minimum":1,"description":"1-based order of this team's substitutions."},"minute":{"type":"integer","minimum":1,"description":"The minute of the change, counted continuously: 58 for anything from 58:00 to 58:59. Stoppage time is not shown separately, so a first-half stoppage-time substitution reads 46' rather than 45+1'."},"elapsedSeconds":{"type":"integer","minimum":0},"playerOn":{"type":"object","properties":{"name":{"type":["string","null"]},"shirtNumber":{"type":["string","null"]}},"required":["name","shirtNumber"],"additionalProperties":false},"playerOff":{"oneOf":[{"type":"null"},{"type":"object","properties":{"name":{"type":["string","null"]},"shirtNumber":{"type":["string","null"]}},"required":["name","shirtNumber"],"additionalProperties":false}],"description":"The player replaced; null when who went off was not recorded."}},"required":["team","subNumber","minute","elapsedSeconds","playerOn","playerOff"],"additionalProperties":false},"SerializedKmi":{"type":"object","properties":{"id":{"type":"string","description":"Stable id of the KMI."},"status":{"type":"string","enum":["pending","marked"],"description":"`marked` once the final internal mark exists, else `pending`."},"type":{"type":["string","null"],"description":"The on-field decision type as logged: yellow, red, penalty_awarded, goal_awarded, offside, etc.","example":"penalty_awarded"},"minute":{"type":["number","null"]},"match":{"type":"object","properties":{"id":{"type":["string","null"]},"round":{"type":["integer","null"],"description":"The competition round number. Null when the match has no round number."},"date":{"type":["string","null"],"format":"date"},"competition":{"type":["string","null"]},"division":{"type":["string","null"]},"homeTeam":{"type":["string","null"]},"awayTeam":{"type":["string","null"]}},"required":["id","round","date","competition","division","homeTeam","awayTeam"],"additionalProperties":false},"team":{"oneOf":[{"type":"null"},{"type":"object","properties":{"side":{"type":"string","enum":["home","away"]},"name":{"type":["string","null"]}},"required":["side","name"],"additionalProperties":false}],"description":"The team the decision concerned, when logged."},"official":{"type":"object","properties":{"userId":{"type":["string","null"]},"name":{"type":["string","null"]},"role":{"type":["string","null"],"description":"The slot the official held on the match: 'center', 'ar1', 'ar2', 'fourth', or a custom role id; null when it can't be resolved."},"refReflectUserId":{"type":["integer","null"],"description":"The official's RefReflect id when linked; null otherwise."}},"required":["userId","name","role","refReflectUserId"],"additionalProperties":false},"clip":{"type":"object","description":"A link to the footage with a 60-second lead-in. Both fields are null when no footage link is available.","properties":{"url":{"type":["string","null"]},"timestampSeconds":{"type":["integer","null"]}},"required":["url","timestampSeconds"],"additionalProperties":false},"coachRating":{"type":["string","null"],"description":"The coach's own on-the-day rating of the call, as recorded."},"internalMark":{"oneOf":[{"type":"null"},{"type":"object","properties":{"verdict":{"type":"string","enum":["correct","incorrect","discussion","no_kmi"]},"decision":{"type":["string","null"],"description":"The decision that was marked, e.g. 'Penalty Awarded'.","example":"Penalty Awarded"},"difficulty":{"type":["string","null"],"description":"The difficulty level picked from the report format's own scale (labels vary by format).","example":"High"},"markedAt":{"type":["string","null"],"format":"date-time"}},"required":["verdict","decision","difficulty","markedAt"],"additionalProperties":false}],"description":"The final internal mark; null while pending."},"externalMark":{"oneOf":[{"type":"null"},{"type":"object","properties":{"verdict":{"type":"string","enum":["correct","incorrect","discussion","no_kmi"]},"decision":{"type":["string","null"],"description":"The decision that was marked, e.g. 'Penalty Awarded'.","example":"Penalty Awarded"},"difficulty":{"type":["string","null"],"description":"The difficulty level picked from the report format's own scale (labels vary by format).","example":"High"},"markedAt":{"type":["string","null"],"format":"date-time"}},"required":["verdict","decision","difficulty","markedAt"],"additionalProperties":false}],"description":"The external review mark; null when none was recorded."},"updatedAt":{"type":["string","null"],"format":"date-time","description":"When the KMI or either of its marks last changed."}},"required":["id","status","type","minute","match","team","official","clip","coachRating","internalMark","externalMark","updatedAt"],"additionalProperties":false},"MatchIncidentsResponse":{"type":"object","properties":{"match":{"$ref":"#/components/schemas/SerializedIncidentsMatch"},"incidents":{"type":"array","description":"Every goal, card, penalty and offside, in match order (period, then match clock). Shoot-out kicks are under `shootout`, not here.","items":{"$ref":"#/components/schemas/SerializedIncident"}},"substitutions":{"oneOf":[{"type":"null"},{"type":"array","items":{"$ref":"#/components/schemas/SerializedSubstitution"}}],"description":"Null when substitution data is not available for the match, for example when no team sheet has been received. An empty array when team sheets were received and nobody was substituted. Ordered by time, home before away at the same instant."},"shootout":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SerializedShootout"}],"description":"The penalty shoot-out, kick by kick. Null when no shoot-out kicks were logged."},"summary":{"type":"object","description":"Counts per team. `unassigned` holds decisions logged without a team.","properties":{"home":{"type":"object","properties":{"goals":{"type":"integer"},"yellowCards":{"type":"integer"},"redCards":{"type":"integer"},"penalties":{"type":"integer"},"offsides":{"type":"integer"}},"required":["goals","yellowCards","redCards","penalties","offsides"],"additionalProperties":false},"away":{"type":"object","properties":{"goals":{"type":"integer"},"yellowCards":{"type":"integer"},"redCards":{"type":"integer"},"penalties":{"type":"integer"},"offsides":{"type":"integer"}},"required":["goals","yellowCards","redCards","penalties","offsides"],"additionalProperties":false},"unassigned":{"type":"object","properties":{"goals":{"type":"integer"},"yellowCards":{"type":"integer"},"redCards":{"type":"integer"},"penalties":{"type":"integer"},"offsides":{"type":"integer"}},"required":["goals","yellowCards","redCards","penalties","offsides"],"additionalProperties":false}},"required":["home","away","unassigned"],"additionalProperties":false}},"required":["match","incidents","substitutions","shootout","summary"],"additionalProperties":false},"MetaResponse":{"type":"object","properties":{"keyId":{"type":"string","example":"aB3dE7gH9kLp"},"tenantId":{"type":"string"},"associationIds":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"string"}}],"description":"null means the key can read every association in its tenant."},"scopes":{"type":"array","items":{"type":"string","enum":["matches:read","reports:read","coach-data:read","incidents:read","kmis:read"]}},"rateLimitPerHour":{"type":"number"}},"required":["keyId","tenantId","associationIds","scopes","rateLimitPerHour"],"additionalProperties":false},"Pagination":{"type":"object","properties":{"page_size":{"type":"integer","minimum":1,"maximum":100},"next_cursor":{"oneOf":[{"type":"null"},{"type":"string"}],"description":"Opaque cursor for the next page. Pass it back unchanged as '?cursor='. Do not construct or decode it."},"has_more":{"type":"boolean"}},"required":["page_size","next_cursor","has_more"],"additionalProperties":false},"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_parameter","unauthorized","key_expired","scope_not_permitted","association_not_permitted","not_found","match_not_full_time","rate_limited","server_error"]},"message":{"type":"string"},"detail":{"type":"object","additionalProperties":true,"description":"Present on some error codes. The shape depends on 'code'."}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}