API changelog

INFO

Change log (updated 12 November 2026)

Latest change: added documentation for the production court-status endpoints for lighting automation, including request/result polling, freshness and offline-camera handling.

12 November 2026

Newly documented: court-status endpoints for lighting automation, available through the production Partner API.

• POST /clutchcam/court-status/request accepts a camera ID and returns HTTP 202 with a UUID job ID.
• POST /clutchcam/court-status/result returns HTTP 202 while processing, or HTTP 200 with OCCUPIED, EMPTY or LIGHTS_OFF when complete.
• Requests may reuse an observation from the previous five minutes. Call /request again for an updated observation; polling an existing job does not refresh it.
• Offline or unavailable cameras can produce HTTP 409. Capture failures and timeouts return non-2xx responses with court_status: null; preserve the current light state.
• These endpoints report court observations and do not switch lights.

Court Status API — Integration Guide

3 November 2026

Corrections to the Clutch Partner API page. The API did not change, so these describe how it already behaves.

Corrected:

• GET /video/{video_id}/results: HTTP 202 also covers recordings that will never have results (CANCELLED, FAILED_DEVICE_OCCUPIED, FAILED_DEVICE_OFFLINE) and UPLOAD_FAILED. During DELAYED_PROCESSING it returns HTTP 200 with only video or an empty outputs list.
• GET /clutchcam/device/{device_id}/scheduled: returns HTTP 404 when nothing is scheduled.
• POST /partner/player-links: a new connect link replaces the player's earlier unused connect links, whichever recording they were for. Only tag links for different recordings can be open at the same time.
• POST /auth/login: HTTP 401 also means API access is not enabled for the account.
• Errors: added the {"errors": {"detail": "..."}} format and the HTTP 400 for a missing Authorization header.

Newly documented:

• run_version on video.status_changed. A reprocess raises it and renumbers every player-N ID, so rebuild anything stored against the old IDs.
• POST /clutchcam/device/{device_id}/schedule defaults: recording_type is match and game_type is doubles.
• Camera status values, required /start fields, and /start, /stop and /schedule errors, including HTTP 429. Through api.clutchapp.io, a rate-limited /start currently returns HTTP 200 with an error body.
• rating_confidence, rating_provisional and rated_matches on GET /partner/players/{partner_player_id}/history, linked_at on already-linked player links, null pair when a player leaves their slot, and deleted: false on DELETE /partner/webhook.
• POST /clutchcam/device/{device_id}/start limits: max_recording_duration_min must be 1 to 120, and a missing or invalid required field returns {"message": "Invalid request body"}.
• PATCH /partner/recordings/{video_id}/annotations: how slots work, with examples for assigning, moving and ungrouping players, and the common causes of 400 invalid_request.

Also corrected on Partner API Documentation:

• Tokens last 12 hours, not 24.
• /start and /stop return recording_started_at and the lower-case camera status.
• /results returns app_link, court_keypoints and clip- keys. It does not return the highlight keys shown in the old sample.
• DELETE /video/{video_id}/cancel returns a message with the scheduled times, and HTTP 422 for any status other than SCHEDULED.

29 October 2026

Partner account linking and annotation APIs are live in production. Integration examples and screen flows cover:

• POST /partner/player-links with purpose: "annotation", opaque state and an optional return_url. Already authorized players skip the webview.
• GET /partner/players/{partner_player_id}/link to verify the current Clutch account and annotation permission.
• GET/PATCH /partner/recordings/{video_id}/annotations to load crops and atomically save grouping, skipped tracks, player assignments and teams. Assign using either partner or Clutch IDs. Repeating the saved edit is idempotent; conflicting edits require a reload.

The guide also documents callback and webhook responses, plus shared 12-hour tokens and bounded login retries.

29 September 2026 0730AM UTC

Court keypoints, multi-match recordings, and mock cameras. Live in production.

• GET /video/{video_id}/results returns court_keypoints: the court points the AI used for the recording, in pixels of a 1920×1080 frame, or null when none were saved. Current padel cameras label tol, tor, point_7 and point_9.
• POST /clutchcam/device/{device_id}/start and /schedule accept "multi_match": true for recordings of several back-to-back matches with different players, such as an americano. match.json then includes a periods list with each match's teams and stats, and each match gets new player-N IDs. It needs game_type: doubles; other game types return 400. Through api.clutchapp.io, /start does not pass multi_match on yet, so use /schedule until it does.
• Mock cameras: CCC Mock Padel 2 now replays a 99-minute doubles match in which the pairs change ends three times, and CCC Mock Padel 3 a 120-minute americano processed as multi-match. Mock recordings now return match.json, player_crop_urls.json and highlight_urls.json from /results.
• Documentation: added the Shot Dictionary for the shot and outcome counts in match.json, and corrected the schedule conflict status to 409.

17 September 2026 1156PM UTC

Player tagging for Partners. Live in production since 18 September 2026.

• POST /partner/player-links now issues two kinds of link. A connect link, for a player who has not linked yet, lasts 24 hours and works once. A tag link, for a linked player with a video_id, lasts 7 days, can be opened again, and only works for the linked Clutch account. Links for different recordings can be open at the same time.
• POST /partner/player-links accepts an optional return_url, which must match a URL registered for the Partner account. The hosted flow sends the player back to it with status (linked or tagged), video_id, and partner_player_id. An unregistered URL returns 400 return_url_not_allowed.
• New GET /partner/recordings/{video_id}/players: the recording's player slots, each with its team (pair) and the linked Partner player holding it.
• GET /partner/players/{partner_player_id}/history matches now include ai_player_id, the slot the player holds in that recording.
• New webhook event player.identification_changed, sent when a linked Partner player gains, changes, or loses their slot in a Partner-owned recording. It carries an event_id for deduplication; reconcile with the players endpoint.
• Players who arrive through a partner link identify the players, matching the AI's player crops to each other, before they tag themselves. The match page opens on that step until someone has completed it.

13 September 2026 1207PM UTC

Added per-selector rally clips to GET /video/{video_id}/results. Previously these were only available by downloading and parsing highlight_urls.json; each one now has its own output key.

• Key format: clip-<selector>-<n> (portrait/autopan) and clip-<selector>-landscape-<n> (landscape). Thumbnails: clip-<selector>-thumbnail-<n> and clip-<selector>-thumbnail-landscape-<n>.
• <selector> is how the rally was picked, e.g. longest-rally or pose-based. <n> starts at 1 and matches the clip's file number.
• Which selectors appear, and how many clips each has, varies by recording. Treat any clip- key as a rally clip rather than relying on a fixed list; new selectors may be added without notice.
• Only returned when status is OK or COMPLETED (not the empty-court statuses). Watermarked variants are not exposed.
• JavaScript parsing example: Parsing highlight clips from results (JavaScript)

Example:

{ "key": "clip-longest-rally-1", "url": "https://xxxx/XXXX.mp4" },
{ "key": "clip-longest-rally-thumbnail-1", "url": "https://xxxx/XXXX.jpg" },
{ "key": "clip-longest-rally-landscape-1", "url": "https://xxxx/XXXX.mp4" },
{ "key": "clip-pose-based-1", "url": "https://xxxx/XXXX.mp4" }

Parsing highlight clips from results (JavaScript)

26 August 2026 0226PM UTC

Added delayed_processing and delayed_processing_since to GET /video/{video_id}/status, and delayed_processing to GET /partner/recordings.

31 July 2026 1322PM UTC

Reencoding from H264 to H265. Link here