# Statbox Partner API

Complete public reference for the Stats API product. This file is static HTML-free Markdown so AI readers and crawlers can load every endpoint without executing JavaScript.

Human UI: https://www.statbox.co/docs/api  
This file: https://www.statbox.co/docs/api.md  
AI index: https://www.statbox.co/llms.txt  
Request a key on WhatsApp: https://wa.me/96170510509?text=Hello%21%20I%20would%20like%20to%20request%20Partner%20API%20access.

## 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

Send the API key on every request.

```
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

| Method | Endpoint | Purpose |
| --- | --- | --- |
| POST | `?endpoint=stats-request` | Create a game from Drive/YouTube or ask for an upload-box email |
| GET or POST | `?endpoint=stats-result` | Full match JSON for that game only |
| GET or POST | `?endpoint=player-stats` | One player from that game |
| GET or POST | `?endpoint=stats-csv` | Spreadsheet of that game |

## 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": string, "team": "A" or "B", "external_id": string, "jersey_number": 0-99 }`. Set `external_id` if you will fetch that player later with `player-stats`.
- `external_reference` (string, max 80). Your booking or match id.
- `date` (YYYY-MM-DD). Optional. Statbox fills a default if omitted.
- `start_time` / `end_time` (HH:MM 24h). Optional.
- `sport` (`football` or `padel`). Optional. Default football.
- `contact_name`, `contact_phone`. Optional.

### Example: YouTube

```bash
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

```bash
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

```bash
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)

```json
{
  "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. If `upload_via_email` was true, `upload_link` is the Statbox upload page and that page is also emailed.

## 2. Ready email

Statbox analysts process the game. There is no 24-hour cutoff.

The email to `notify_email` includes:

- CSV of every player’s stats
- each player’s highlight link
- each player’s screenshot link
- the game highlight link
- the `match_id`

The email does not include a Statbox join link.

## 3. GET or POST ?endpoint=stats-result

Returns the specific game you requested. Nothing else.

Identify the game with one of: `match_id`, `key_code`, or `external_reference`.

```bash
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`.

When ready, the JSON includes:

- `match_id`, `key_code`, `status`, `sport`, `date`
- `score` (`team_a`, `team_b`)
- `game_highlight_url`
- `players[]` with name, team, `external_id`, stats, `highlight_url`, `screenshot_url`

## 4. GET or POST ?endpoint=player-stats

One player from that same game.

Required: the game id (`match_id` or `key_code` or `external_reference`) plus one of `external_id`, `slot_number`, or `player_name`.

```bash
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"
```

Response includes `match_id`, `status`, `score`, `game_highlight_url`, and `player` (stats, highlight, screenshot).

## 5. GET or POST ?endpoint=stats-csv

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

```bash
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" }`.

| HTTP | Meaning |
| --- | --- |
| 401 | Bad or missing API key |
| 403 | This key cannot use this product, or the key is disabled |
| 400 | Missing or invalid fields (for example a non-Drive/YouTube `footage_url`) |
| 404 | That game was not requested with this key |
| 429 | Too many requests this minute, or this key’s monthly game cap is reached |

## Integration notes for apps and AI assistants

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. Do not send raw MP4 URLs except via the emailed upload box. Public Drive or YouTube only, or `upload_via_email: true`.