Create matches at your Clutch venues and push live scores from your own scoring system. Clutch shows the score on the court overlay, records matches on camera courts and publishes each event on a public page.
Base URL
https://partners.theclutchsports.org/v1
Authentication
X-API-Key header on every request
Writes
Idempotency-Key header on every POST and PUT
Format
JSON over HTTPS. Successful responses wrap the result in data.
Quickstart
A match goes through four calls. The script below runs all of them; replace the key and it works as is.
Find your venue and courtGET /facilities returns the venues and courts your key can use.
Create a matchPOST /quick-matches with the sport, the two team names and the venue. The match is live at once.
Push the scorePUT /quick-matches/{id}/score each time the score changes.
End the matchPOST /quick-matches/{id}/complete, or send "status": "completed" with the last score.
bash
KEY="ck_live_..."
BASE="https://partners.theclutchsports.org/v1"
# 1. Your venues and courts: take a facility id and a court id from here
curl -sS "$BASE/facilities" -H "X-API-Key: $KEY"
FACILITY="<facility id>"
COURT="<court id>"
# 2. An event to group the matches (needed for recording)
EVENT=$(curl -sS -X POST "$BASE/quick-tournaments" \
-H "X-API-Key: $KEY" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Friday Night Open\",\"facilityId\":\"$FACILITY\"}" | jq -r .data.id)
# 3. A match
MATCH=$(curl -sS -X POST "$BASE/quick-matches" \
-H "X-API-Key: $KEY" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d "{\"sport\":\"pickleball\",\"teamAName\":\"Asha / Ravi\",\"teamBName\":\"Meera / Karan\",
\"facilityId\":\"$FACILITY\",\"courtId\":\"$COURT\",\"quickTournamentId\":\"$EVENT\",
\"externalId\":\"my-match-1001\"}" | jq -r .data.id)
# 4. The score, every time it changes
curl -sS -X PUT "$BASE/quick-matches/$MATCH/score" \
-H "X-API-Key: $KEY" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"teamAScore":7,"teamBScore":5,"status":"in_progress",
"pickleball":{"score_a":7,"score_b":5,"games_a":0,"games_b":0,
"current_game_number":1,"total_games":3,"serving_team":"A"}}'
# 5. End the match (no body, no Content-Type)
curl -sS -X POST "$BASE/quick-matches/$MATCH/complete" \
-H "X-API-Key: $KEY" -H "Idempotency-Key: $(uuidgen)"
Authentication
Send your API key in the X-API-Key header on every request. Keys start with ck_live_.
A key is shown once, when Clutch issues it. Clutch does not keep a readable copy. If you lose it, ask for a new one; the old one is then revoked.
A key is tied to venues. It can create matches only at the venues Clutch granted it, and can read or score only the matches it created.
Keep it on your server. Never ship it in a mobile app or a web page.
Idempotency
Every POST and PUT must carry an Idempotency-Key header: any unique string up to 120 characters. A UUID works well. Use a new key for each new action.
If a request times out or the connection drops, send it again with the same key. Within 24 hours Clutch returns the first response again, with the header Idempotent-Replay: true, and does nothing twice.
Matches and events also accept your own id in externalId. Creating one with an externalId you already used returns the existing record with "deduped": true instead of a duplicate.
Rate limits
Each key has a per-minute request limit, set when the key is issued (60 a minute unless Clutch agreed otherwise). Over the limit, requests return 429 rate_limited: wait a few seconds and retry.
Push a score only when it changes. One push per point is well inside the limit for several courts at once.
Endpoints
All paths are relative to https://partners.theclutchsports.org/v1.
GET/facilities
Venues and courts
The venues your key can use, each with its courts. Start here: every match needs a facilityId from this list.
An event groups matches under one name and one public page. A match must belong to an event to be recorded.
Field
Type
Notes
namerequired
string
Shown on the public page.
facilityId
uuid
One of your venues.
externalId
string
Your own id for the event.
Creating an event that already exists returns the existing one with status 200 and "deduped": true. An event counts as existing when it has the same externalId, or the same name at the same venue.
A completed match cannot be scored again: further pushes return 409 match_completed.
POST/quick-matches/{id}/complete
End a match
Marks the match completed and stops its recording. Send no body and no Content-Type header; the Idempotency-Key header is still required. Calling it on a match that is already completed is safe.
Every score push carries one block named after the match's sport. Fields marked required must be present on every push. Anything else you add to the block is stored and returned unchanged.
Block name: pickleball, badminton, tabletennis, squash or volleyball. All five share one shape.
Field
Type
Meaning
score_arequired
number
Team A's points in the current game.
score_brequired
number
Team B's points in the current game.
games_arequired
number
Games (or sets) team A has won.
games_brequired
number
Games (or sets) team B has won.
current_game_numberrequired
number
The game being played, starting at 1.
total_gamesrequired
number
Best of how many, for example 3.
serving_team
string
"A" or "B".
server_number
number
Pickleball doubles: 1 or 2.
Cricket
Block name: cricket.
Field
Type
Meaning
innings_norequired
number
1 or 2.
batting_team_namerequired
string
The side batting now.
runsrequired
number
wicketsrequired
number
oversrequired
string
Overs bowled, as text: "12.4".
max_oversrequired
number
Overs per innings.
target, crr, rrr, extras
number
Optional.
striker, non_striker, bowler
object
Optional player lines, for example { "name": "Rohit", "runs": 42, "balls": 28 }.
Recording and overlay
Overlay. A match created with a courtId appears on that court's overlay, and each score push updates it, usually within a second. There is nothing else to call.
Recording. On a court with a Clutch camera, a match created with a quickTournamentId starts recording when it is created and stops when it is completed.
Video links. Responses do not include video links by default. Viewers watch on the event's public page. If your product needs the links themselves, ask Clutch to switch them on for your key; GET /quick-matches/{id} then includes a recording object.
Public pages
Each event has a public page with its matches, scores and videos. Share it with players: