Statbox Partner API

Complete public reference for the Stats API. This page is static HTML so ChatGPT and other readers can load every endpoint without JavaScript.

Styled UI: https://www.statbox.co/docs/api · Markdown: https://www.statbox.co/docs/api.md · llms.txt · Request a key: WhatsApp

What this API does

A partner sends a football or padel game as a public Google Drive or YouTube link, or asks Statbox to email an upload box. Statbox analysts process the game. When it is ready, Statbox emails a CSV of player stats plus highlight, screenshot, and game-highlight links. The partner then pulls that same game into their own app.

There is no venue camera step. The partner does not pick a venue. The ready email does not include a Statbox join link.

Base URL

https://pfmdviiiwbpcutebhlkw.supabase.co/functions/v1/statbox-partner-api

Every call is this URL plus ?endpoint=NAME.

Authentication

Authorization: Bearer sbx_live_YOUR_API_KEY
Content-Type: application/json

Keys begin with sbx_live_. A key can be unlimited or capped to a number of games per calendar month (UTC). You can only read games created with that key.

Endpoints

1. POST ?endpoint=stats-request

Creates the Statbox game. Does not wait for stats.

Required

• notify_email (string). When the game is ready, Statbox emails this address.

One of these two footage options (not both)

• footage_url (string). Public Google Drive or YouTube https link only. Other URLs are rejected.
• upload_via_email (boolean true). Statbox emails notify_email a one-time Statbox upload page.

Optional

• players (array). Each item: name, team A or B, external_id, optional jersey_number 0-99. Set external_id if you will fetch that player later.
• external_reference (string, max 80). Your booking or match id.
• date (YYYY-MM-DD), start_time / end_time (HH:MM 24h), sport (football or padel), contact_name, contact_phone.

Example: YouTube

curl -X POST "https://pfmdviiiwbpcutebhlkw.supabase.co/functions/v1/statbox-partner-api?endpoint=stats-request" \
  -H "Authorization: Bearer sbx_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notify_email": "ops@partner.com",
    "footage_url": "https://youtu.be/VIDEO_ID"
  }'

Example: Google Drive

curl -X POST "https://pfmdviiiwbpcutebhlkw.supabase.co/functions/v1/statbox-partner-api?endpoint=stats-request" \
  -H "Authorization: Bearer sbx_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notify_email": "ops@partner.com",
    "footage_url": "https://drive.google.com/file/d/FILE_ID/view",
    "players": [
      { "name": "Ahmed Khalil", "team": "A", "external_id": "player-88" },
      { "name": "Omar Haddad", "team": "B", "external_id": "player-91" }
    ],
    "external_reference": "BOOKING-123"
  }'

Example: email an upload box

curl -X POST "https://pfmdviiiwbpcutebhlkw.supabase.co/functions/v1/statbox-partner-api?endpoint=stats-request" \
  -H "Authorization: Bearer sbx_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notify_email": "ops@partner.com",
    "upload_via_email": true
  }'

Success response (HTTP 201)

{
  "match_id": "uuid",
  "key_code": "ABC123",
  "status": "under_review",
  "notify_email": "ops@partner.com",
  "footage_url": "https://youtu.be/VIDEO_ID",
  "footage_source": "youtube",
  "upload_link": null,
  "players_accepted": 2,
  "poll_url": "?endpoint=stats-result&match_id=uuid",
  "csv_url": "?endpoint=stats-csv&match_id=uuid",
  "player_stats_url": "?endpoint=player-stats&match_id=uuid",
  "message": "Game created. When analysis is done we email the CSV, highlight links, and screenshot links."
}

Save match_id. You need it for the other endpoints.

2. Ready email

Statbox analysts process the game. There is no 24-hour cutoff. The email to notify_email includes a CSV of every player’s stats, each player’s highlight link and screenshot link, the game highlight link, and the match_id. It does not include a Statbox join link.

3. GET or POST ?endpoint=stats-result

Returns the specific game you requested. Identify it with match_id, key_code, or external_reference.

curl -X GET "https://pfmdviiiwbpcutebhlkw.supabase.co/functions/v1/statbox-partner-api?endpoint=stats-result&match_id=MATCH_ID_FROM_STEP_1" \
  -H "Authorization: Bearer sbx_live_YOUR_API_KEY"

status is under_review while Statbox works, then ready. Ready JSON includes match_id, key_code, status, sport, date, score (team_a, team_b), game_highlight_url, and players[] with name, team, external_id, stats, highlight_url, screenshot_url.

4. GET or POST ?endpoint=player-stats

One player from that same game. Send the game id plus one of external_id, slot_number, or player_name.

curl -X GET "https://pfmdviiiwbpcutebhlkw.supabase.co/functions/v1/statbox-partner-api?endpoint=player-stats&match_id=MATCH_ID_FROM_STEP_1&external_id=player-88" \
  -H "Authorization: Bearer sbx_live_YOUR_API_KEY"

5. GET or POST ?endpoint=stats-csv

Same match as a CSV file. Same data as the email attachment.

curl -X GET "https://pfmdviiiwbpcutebhlkw.supabase.co/functions/v1/statbox-partner-api?endpoint=stats-csv&match_id=MATCH_ID_FROM_STEP_1" \
  -H "Authorization: Bearer sbx_live_YOUR_API_KEY" \
  -o statbox-stats.csv

Errors

All errors are JSON: { "error": "message" }.

Integration notes

1. Store the API key as a server-side secret. Do not put it in a mobile app binary.
2. Call stats-request once per game. Save match_id.
3. Wait for the ready email, or poll stats-result until status is ready.
4. Use player-stats with your external_id to show one player in your product.
5. Do not send venue ids. Public Drive or YouTube only, or upload_via_email true.