clutch. Partner API v1
OpenAPI Support

Integration guide

Clutch Partner API

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.

  1. Find your venue and courtGET /facilities returns the venues and courts your key can use.
  2. Create a matchPOST /quick-matches with the sport, the two team names and the venue. The match is live at once.
  3. Push the scorePUT /quick-matches/{id}/score each time the score changes.
  4. 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_.

bash
curl https://partners.theclutchsports.org/v1/facilities \
  -H "X-API-Key: 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.

Response 200

json
{
  "data": [
    {
      "id": "3d9f2a61-7c4e-4b0a-9e15-6a8d2c7b4f10",
      "name": "Your Venue",
      "city": "Bengaluru",
      "state": "Karnataka",
      "courts": [
        { "id": "5c1f0c0e-8f0a-4d5b-9a53-2d0f6b7f1a11", "name": "Court 1", "sport": "Pickleball" }
      ]
    }
  ]
}
POST/quick-tournaments

Create an event

An event groups matches under one name and one public page. A match must belong to an event to be recorded.

FieldTypeNotes
namerequiredstringShown on the public page.
facilityIduuidOne of your venues.
externalIdstringYour 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.

Response 201

json
{
  "data": {
    "id": "8a3b4c2e-6f1d-4e9a-b7c5-0d2e1f3a4b5c",
    "name": "Friday Night Open",
    "facilityId": "3d9f2a61-7c4e-4b0a-9e15-6a8d2c7b4f10",
    "createdAt": "2026-11-20T13:05:11.482Z"
  }
}
GET/quick-tournaments

List events

Your active events, newest first, up to 100. Add ?facilityId=<uuid> to list one venue only.

Response 200

json
{
  "data": [
    {
      "id": "8a3b4c2e-6f1d-4e9a-b7c5-0d2e1f3a4b5c",
      "name": "Friday Night Open",
      "facilityId": "3d9f2a61-7c4e-4b0a-9e15-6a8d2c7b4f10",
      "facilityName": "Your Venue",
      "createdAt": "2026-11-20T13:05:11.482Z",
      "matchCount": "12"
    }
  ]
}
POST/quick-matches

Create a match

Creates a match and starts it. Its status is in_progress from the first moment, so the court overlay can show it before the first point.

FieldTypeNotes
sportrequiredstringpickleball, badminton, tabletennis, squash, volleyball or cricket.
teamANamerequiredstringFor doubles, both names, for example "Asha / Ravi".
teamBNamerequiredstring
facilityIdrequireduuidOne of your venues.
courtIduuidA court at that venue. Needed for the court overlay and for recording.
quickTournamentIduuidOne of your events at this venue. Needed for recording.
externalIdstringYour own id for the match. Recommended.
matchFormatstringsingles or doubles.

Response 201

json
{
  "data": {
    "id": "f2b7c9d4-1e3a-4b6c-8d5e-7a9b0c1d2e3f",
    "externalId": "my-match-1001",
    "scoringSource": "self"
  }
}

A second request with the same externalId returns the first match with status 200 and "deduped": true.

PUT/quick-matches/{id}/score

Push the score

Send the whole current score each time it changes. Every push replaces the previous one, so a missed push is corrected by the next.

FieldTypeNotes
teamAScorerequirednumberThe headline score for team A.
teamBScorerequirednumberThe headline score for team B.
sport blockrequiredobjectNamed after the match's sport, for example pickleball. See score blocks by sport.
scoreTextstringText shown as the score, for example "11-7 (1-0)". Defaults to teamAScore-teamBScore.
statusstringin_progress (default) or completed. completed ends the match.
json
{
  "teamAScore": 11,
  "teamBScore": 7,
  "scoreText": "11-7 (1-0)",
  "status": "in_progress",
  "pickleball": {
    "score_a": 11, "score_b": 7,
    "games_a": 1, "games_b": 0,
    "current_game_number": 2, "total_games": 3,
    "serving_team": "A", "server_number": 2
  }
}

Response 200

json
{
  "data": {
    "id": "f2b7c9d4-1e3a-4b6c-8d5e-7a9b0c1d2e3f",
    "status": "in_progress",
    "score": "11-7 (1-0)",
    "scoringSource": "self",
    "sport": "pickleball",
    "scoreboard": { "score_a": 11, "score_b": 7, "games_a": 1, "games_b": 0,
                    "current_game_number": 2, "total_games": 3,
                    "serving_team": "A", "server_number": 2 }
  }
}

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.

Response 200

json
{ "data": { "id": "f2b7c9d4-1e3a-4b6c-8d5e-7a9b0c1d2e3f", "status": "completed" } }
GET/quick-matches/{id}

Read a match

The match as Clutch holds it, with the last score you pushed.

Response 200

json
{
  "data": {
    "id": "f2b7c9d4-1e3a-4b6c-8d5e-7a9b0c1d2e3f",
    "teamA": "Asha / Ravi",
    "teamB": "Meera / Karan",
    "sport": "pickleball",
    "status": "in_progress",
    "score": "11-7 (1-0)",
    "scoringSource": "self",
    "externalId": "my-match-1001",
    "facilityId": "3d9f2a61-7c4e-4b0a-9e15-6a8d2c7b4f10",
    "courtId": "5c1f0c0e-8f0a-4d5b-9a53-2d0f6b7f1a11",
    "quickTournamentId": "8a3b4c2e-6f1d-4e9a-b7c5-0d2e1f3a4b5c",
    "createdAt": "2026-11-20T13:06:40.120Z",
    "scoreboard": { "score_a": 11, "score_b": 7, "games_a": 1, "games_b": 0,
                    "current_game_number": 2, "total_games": 3, "serving_team": "A" },
    "partnerScore": { "teamAScore": 11, "teamBScore": 7, "scoreText": "11-7 (1-0)",
                      "status": "in_progress", "updated_at": "2026-11-20T13:21:07.915Z" }
  }
}

Score blocks by sport

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.

Pickleball, badminton, table tennis, squash, volleyball

Block name: pickleball, badminton, tabletennis, squash or volleyball. All five share one shape.

FieldTypeMeaning
score_arequirednumberTeam A's points in the current game.
score_brequirednumberTeam B's points in the current game.
games_arequirednumberGames (or sets) team A has won.
games_brequirednumberGames (or sets) team B has won.
current_game_numberrequirednumberThe game being played, starting at 1.
total_gamesrequirednumberBest of how many, for example 3.
serving_teamstring"A" or "B".
server_numbernumberPickleball doubles: 1 or 2.

Cricket

Block name: cricket.

FieldTypeMeaning
innings_norequirednumber1 or 2.
batting_team_namerequiredstringThe side batting now.
runsrequirednumber
wicketsrequirednumber
oversrequiredstringOvers bowled, as text: "12.4".
max_oversrequirednumberOvers per innings.
target, crr, rrr, extrasnumberOptional.
striker, non_striker, bowlerobjectOptional 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:

url
https://tournament.theclutchsports.com/qt/<quickTournamentId>

Errors

Errors return a JSON body with a stable error code and, where it helps, a message. Branch on the code, not the message.

json
{ "error": "facility_forbidden", "message": "This API key cannot operate on the requested facility" }
StatusCodeWhat to do
400bad_requestA field is missing or has the wrong type. The message names it.
400missing_idempotency_key
invalid_idempotency_key
Add the header to the POST or PUT; keep it to 120 characters.
400facility_not_in_tournamentThe event is not held at that venue.
401missing_api_key
invalid_api_key
Check the X-API-Key header. A revoked key also returns this.
403facility_required
facility_forbidden
Send a facilityId from GET /facilities.
403court_forbiddenThe court is not at that venue.
403tournament_forbidden
match_forbidden
The event or match was not created by your key.
403scoring_mode_forbiddenLeave scoringMode out of the request.
404not_foundNo match with that id, or no such endpoint.
409match_completedThe match has ended. Create a new one.
409mode_conflictThe match is not scored through this API.
413payload_too_largeRequest bodies are limited to 256 KB.
429rate_limitedWait a few seconds and retry.
5xxupstream_unavailable and othersRetry with the same Idempotency-Key, backing off between attempts.

OpenAPI

The full specification, for Postman, Insomnia or a client generator.