Sessions

A session is one submitted game and everything the pipeline produced for it. The same object shape is returned by every endpoint and inside every webhook event, so you parse it once.

Sources

POST /v1/sessions takes a source. type is optional — Hooper derives it from the URL, and a Veo link is always routed to the Veo path even if you say url.

Upload your own file
Public URL
Veo

Three steps: create an upload, PUT the bytes to the returned resumable URL, then submit. size must be the file’s exact length in bytes, because upload_url accepts exactly that many. expires_in_seconds is how long upload_url accepts the PUT; the stored file doesn’t expire.

# 1. create the upload
curl https://zeus.hooper.gg/v1/uploads \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "content_type": "video/mp4", "size": 2147483648 }'
# → { "id": "up_3f9a…", "upload_url": "https://storage.googleapis.com/…", "expires_in_seconds": 604800 }

# 2. PUT the file (GCS resumable protocol — a single PUT works for most files)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @game.mp4

# 3. submit
curl https://zeus.hooper.gg/v1/sessions \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "source": { "type": "upload", "upload_id": "up_3f9a…" } }'

Submitting before the bytes have landed returns 409 upload_incomplete.

Any public https:// link to an MP4 or MOV. Hooper downloads it server-side.

{ "source": { "type": "url", "url": "https://cdn.example.com/games/2026-08-26.mp4" } }

The host must be publicly resolvable (private and link-local addresses are rejected).

A public Veo match page or CDN link. No download on your side.

{ "source": { "type": "veo", "url": "https://app.veo.co/matches/20260826-acme-vs-north/" } }

Request fields

Field	Notes
`group`	A `grp_…` under your organization. Omit it and the session lands in your organization’s own private group.
`metadata`	Up to 20 string key/values; echoed on the session and in every event.
`options`	Describes how the video was recorded. See Recording options.
`branding`	Your own opening cover and corner logo on the processed video. See Branding.
`rosters`	Each team’s players, so the players Hooper detects come back with your names and your own ids. See Rosters.

The credit hold

Submitting places a hold on your balance: an estimate (from the file size for uploads, 2 hours for URL and Veo sources), never more than your available balance. Before processing, Hooper measures the video and resizes the hold to its real cost; you’re charged for that measured length. The duration_seconds on the returned session object is the measured length. It is null until the session is processed. See Billing.

Recording options

Everything under options is optional. Values are case-sensitive, and anything outside the listed values is rejected with 400 parameter_invalid, with param naming the field (for example options.camera_setup). Four options change how the video is analysed:

Option	Values	Default	Effect
`camera_setup`	`stationary`, `panning`	`stationary`	Where Hooper looks for the hoop. `stationary` means the camera stays still with the hoop in the upper middle of the frame. Hooper looks only there: roughly the middle third horizontally, and the top half vertically. `panning` means the camera follows the play, and Hooper searches the whole frame.
`jerseys`	`auto`, `enabled`, `disabled`	`auto`	Whether Hooper reads jersey numbers to tell players apart. See Jerseys.
`session_mode`	`game`, `practice`, `shootaround`	`game`	`game`: two teams, split using the team names below. `practice`: the same analysis without the team split. `shootaround`: a shooting workout with no teams and no free-throw detection.
`session_type`	`solo`, `1v1`, `2v2`, `3v3`, `4v4`, `5v5`	`5v5`	The format. In `game` and `practice` it sets the default `num_players`, and `3v3`, `4v4` and `5v5` turn on free-throw detection.

If your camera is fixed but the hoop is not in the upper middle of the frame (for example a wide gym camera), send camera_setup: "panning". Otherwise Hooper finds no hoop and the session fails with no_hoops.

The rest are saved with the session but do not change the results the API returns:

Option	Values	Default	Meaning
`court_type`	`high_school`, `ncaa_women`, `ncaa_men`, `fiba`, `wnba`, `nba`	`ncaa_men`	The court markings, which set the 3-point line distance. A shot’s `is_three_point` comes from the video analysis.
`point_system`	`1`, `2`, `3`	`1`	`1` = 2s and 3s, `2` = 1s and 2s, `3` = every basket is worth 1. Shot `points` and `totals` in the API always use standard scoring (2 or 3 per basket, 1 per free throw).
`recording_setup`	`tripod`, `ground`	`tripod`	`tripod`: a tripod or another raised mount. `ground`: low to the floor, such as a phone propped against a bottle.
`num_players`	`1`–`10`	from `session_type`	Players on the court. In `game` and `practice` it defaults to what `session_type` implies (`5v5` gives 10), so send it only to override. `shootaround` has no default.
`model`	`beta`, `flash`	`flash`	The processing pipeline. `flash` is the single-pass pipeline: faster and cheaper to run. `beta` is the earlier pipeline, with the same results format.
`recording_team_name`	any string	`Team 1`	Your team’s name. Used only in `game` mode. Echoed as `teams.recording.name`. A roster can name the team instead; sending both is refused with `400` and `param: options.recording_team_name`.
`opponent_team_name`	any string	`Team 2`	The opposing team’s name. Used only in `game` mode. Echoed as `teams.opponent.name`; the same rule as above applies.

A full request, for a 5v5 game filmed on a fixed tripod with numbered jerseys:

{
  "source": { "type": "upload", "upload_id": "up_3f9a1c2b7e5d4a08" },
  "metadata": { "external_match_id": "abc-123" },
  "options": {
    "session_type": "5v5",
    "session_mode": "game",
    "camera_setup": "stationary",
    "jerseys": "enabled",
    "court_type": "nba",
    "recording_team_name": "Acme Varsity",
    "opponent_team_name": "North High"
  }
}

Jerseys

jerseys decides whether Hooper reads jersey numbers. Reading them is how Hooper tells players apart in an organized game. It is also what fills in players[].jersey and lets rosters be matched.

Value	What Hooper does	Use it when
`auto` (default)	Looks at five frames from the video and decides whether the players wear numbered team uniforms. If it can’t tell, it doesn’t read numbers, unless you sent `rosters`.	You don’t know in advance.
`enabled`	Always reads numbers.	Players wear numbered uniforms, as in any league game. Recommended with `rosters`.
`disabled`	Never reads numbers, and tells players apart by how they look instead. Can’t be combined with `rosters`.	Pickup games, or bibs without numbers.

When Hooper reads numbers, it groups each player’s actions by number and team:

An action where Hooper couldn’t read the number isn’t credited to any player.
A number has to be read on at least two actions to become a player.

So reading numbers works best when they’re legible in the video. auto gets this right for most videos, but it can decide that a game has no numbered uniforms when it does. Numbers are then not read, and rosters are not matched. If you know the players wear numbers, send enabled.

has_jerseys (true / false) is the older form of this option. It still works, but is deprecated: true means enabled and false means disabled. Send one or the other; a request with both is refused with 400 and param: options.

Branding

Put your own images on the processed video. Both are optional and work with every source type, including Veo.

Field	Where it appears	Image to send
`branding.cover`	Full-frame for the first 5 seconds of `video`.	16:9, ideally 1920×1080. Other shapes are scaled to fill the frame and center-cropped.
`branding.logo`	Lower-right corner of the game footage, on `video` and on every highlight. Not shown over the cover.	A PNG with a transparent background, landscape between about 1.6:1 and 3.6:1 (for example 520×220). See Logo size.

Each image must be a valid PNG, JPEG or WebP of at most 5 MB. Hooper reads the format from the file itself, not from its name or Content-Type.

Sending an image

Send each image as a public URL or as an upload, whichever you have. Use one or the other per image, not both.

Public URL
Upload

Hooper downloads the image when it starts processing the session, before the video.

curl https://zeus.hooper.gg/v1/sessions \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "veo", "url": "https://app.veo.co/matches/20260826-acme-vs-north/" },
    "branding": {
      "cover": { "url": "https://cdn.example.com/brand/cover.jpg" },
      "logo":  { "url": "https://cdn.example.com/brand/logo.png" }
    }
  }'

The URL must be public https:// and answer 200 within 15 seconds. Up to 3 redirects are followed, and private or link-local addresses are rejected, including through a redirect. Hooper keeps its own copy with the session, so the image only needs to stay at that URL until the session is processed. Each new session downloads the URL again, so a changed file applies to the sessions you submit next, not to ones already processed.At submit, Hooper only checks the address. If the image itself is unusable, the session fails during processing (see Branding errors).

Upload the image once, then reuse its id. An image upload is not used up by a submit.

# 1. create the image upload; size is the file's exact length in bytes
curl https://zeus.hooper.gg/v1/uploads \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "content_type": "image/png", "size": 48213 }'
# → { "id": "up_7c1e…", "upload_url": "https://storage.googleapis.com/…", "expires_in_seconds": 604800 }

# 2. PUT the file to upload_url
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @logo.png

# 3. send its id with every session
curl https://zeus.hooper.gg/v1/sessions \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "veo", "url": "https://app.veo.co/matches/20260826-acme-vs-north/" },
    "branding": { "logo": { "upload_id": "up_7c1e…" } }
  }'

expires_in_seconds only limits how long upload_url accepts the PUT. The uploaded image doesn’t expire, so you can keep using its upload_id.

Logo size

A landscape logo between about 1.6:1 and 3.6:1 is drawn at most 260×110 px on the 1920×1080 frame, 48 px from the right edge and 52 px from the bottom. That is enough to cover the wordmark Veo burns into its exports, so on a Veo source your logo replaces Veo’s. A squarer or wider logo is enlarged past that box so it still covers the wordmark: a square logo is drawn at 180×180, for example. Any resolution works, since Hooper scales it. To keep it sharp, send it at least as large as it will be drawn.

What to expect

The session says what it carries. Every session object has "branding": { "cover": true, "logo": true }, set when you submit. A processed session always has every image it lists.
The cover is part of the video. video, every shot’s start_seconds / end_seconds and the measured duration_seconds include its 5 seconds. Those 5 seconds are billed like the rest of the video; branding costs nothing else.
A branded video is always 1920×1080. A portrait recording gets black bars at the sides.

Branding errors

Problems Hooper can see at submit are refused at submit, before anything is held. param names the field (branding.logo is shown; branding.cover works the same way):

Error	`param`	Cause
`400 invalid_request`	`branding.logo`	Neither or both of `url` and `upload_id` were sent.
`400 invalid_request`	`branding.logo.url`	The URL isn’t public `https://`, or is longer than 2,048 characters.
`400 image_invalid`	`branding.logo.upload_id`	The upload isn’t a PNG, JPEG or WebP.
`409 upload_incomplete`	`branding.logo.upload_id`	The upload hasn’t finished, or wasn’t created with an image `content_type`.
`503 branding_save_failed`		Hooper couldn’t save your images. Retry with the same `Idempotency-Key`.

Anything else fails the session. Hooper never processes a video without the branding you asked for. The session ends in failed, the hold is voided (nothing is charged), and you receive session.failed. Its error names the image and says what to fix:

"error": {
  "code": "image_unavailable",
  "param": "branding.logo",
  "message": "The logo image could not be downloaded. Its url must be public https and return the image (status 200) within 15 seconds, with at most 3 redirects. Fix it and resubmit; nothing was charged."
}

`error.code`	Cause
`image_unavailable`	The URL didn’t answer `200` within 15 seconds, redirected more than 3 times, or now points at a private address.
`image_invalid`	The file isn’t a valid PNG, JPEG or WebP, or is corrupt.
`image_too_large`	The file at the URL is over 5 MB.

URL images are downloaded before the video, so a bad URL fails the session within moments of processing starting.

Rosters

Send each team’s players, and the players Hooper detects come back with your names and your own ids. Every highlight.player then points at a player you know, so you can follow a player’s highlights and stats across games, even when rosters change from game to game.

"rosters": {
  "recording": {
    "name": "Acme Varsity",
    "metadata": { "team_id": "lg-t-12" },
    "players": [
      { "jersey": "23", "name": "Ana Silva", "metadata": { "player_id": "lg-4821" } },
      { "jersey": "7",  "name": "Cleo Dias", "metadata": { "player_id": "lg-0937" } }
    ]
  },
  "opponent": {
    "name": "North High",
    "metadata": { "team_id": "lg-t-07" },
    "players": [
      { "jersey": "23", "name": "Bea Costa", "metadata": { "player_id": "lg-7710" } }
    ]
  }
}

recording is your team and opponent the other one, the same two sides as recording_team_name and opponent_team_name. Send one or both: a practice with one squad only needs recording. An empty rosters object is refused with 400 and param: rosters. Each roster:

Field	Required	Notes
`players`	Yes	1 to 200 players, each with a different number.
`name`	No	The team’s name. The same as sending `recording_team_name` / `opponent_team_name`; sending both for one side is refused with `400` and `param` naming the option. Echoed as `teams.<side>.name`.
`metadata`	No	Up to 20 string key/values, with the same limits as the session’s `metadata`. Echoed as `teams.<side>.metadata`. Put your own team id here.

Each player:

Field	Required	Notes
`jersey`	Yes	The number on the player’s jersey: 1 to 3 digits, as a string (`"7"`, `"23"`). Hooper matches players by it.
`name`	No	Up to 50 characters. Returned as `players[].name`.
`metadata`	No	Up to 20 string key/values, with the same limits as the session’s `metadata`. Returned as `players[].metadata`. Put your own player id here.

Two teammates with the same number are refused with 400 and param: rosters.<side>.players, because Hooper could never tell them apart. "7" and "07" count as the same number. The same number on both teams is fine. Rosters are matched by jersey number, so they can’t be sent with jerseys: "disabled" (or has_jerseys: false); that request is refused with 400 and param: options.jerseys.

How players are matched

Hooper reads jersey numbers from the video, then matches the players it detected to your rosters:

One player per number and side. A detected player is named when its number is on the roster of its side. The video doesn’t know which side is yours, so Hooper tries both ways round and keeps the one that names more players. players[].team_id then follows your rosters: 1 is recording, 2 is opponent, and players[].team_name is that side’s name.
Numbers have to be read. Matching uses the numbers Hooper reads, so it depends on jerseys. With the default auto, Hooper decides from the video, and if it can’t tell, your rosters keep numbers on. Send enabled when you know the players wear numbers.
Matching never fails a session. A player whose number couldn’t be read, or isn’t on its side’s roster, comes back without a roster name and with metadata: {}.

What comes back

"teams": {
  "recording": { "name": "Acme Varsity", "metadata": { "team_id": "lg-t-12" } },
  "opponent":  { "name": "North High",   "metadata": { "team_id": "lg-t-07" } }
},
"players": { "object": "list", "total_count": 10, "has_more": false, "data": [
  { "id": "plr_5", "object": "player", "name": "Ana Silva", "jersey": "23",
    "team_id": 1, "team_name": "Acme Varsity",
    "metadata": { "player_id": "lg-4821" }, "stats": { "points": 22, "…": "…" } }
] }

teams is on every session. A side you didn’t name has Hooper’s default name (Team 1 for recording, Team 2 for opponent) and metadata: {}. Each player carries its side as team_id (1 = recording, 2 = opponent) and team_name, the same name as in teams; both are null for a player Hooper couldn’t place on a side. highlight.player and shot.players.* point at the plr_… ids in players. A plr_… id only exists within one session; your metadata is what stays the same from game to game. To collect each player’s highlights across sessions:

highlights_by_player = defaultdict(list)  # your player_id → highlights
for session in sessions:  # each from GET /v1/sessions/{id}
    player_ids = {p["id"]: p["metadata"].get("player_id") for p in session["players"]["data"]}
    for highlight in session["highlights"]["data"]:  # page highlights.url when has_more is true
        highlights_by_player[player_ids.get(highlight["player"])].append(highlight)

Good to know:

Roster players Hooper didn’t detect in the video don’t appear in players. A player is detected once Hooper reads their number on at least two of their actions (see Jerseys).
Hooper can’t read 00 yet, so a player wearing it stays unnamed.
Now and then the video splits one player into two detected players. Both get the same name and metadata, so add their stats up by your id.

Limits

The API accepts the same envelope a Hooper mobile recording produces:

	Limit
Size	≤ 10 GB
Resolution	≤ 1080p (1920×1080, either orientation)
Format	MP4 or MOV, H.264 preferred

Where the size is knowable at submit (an upload’s blob size, a URL’s Content-Length) an oversize video is refused with 400 video_too_large and nothing is held. Resolution is only known once the video is downloaded and probed; if it exceeds the limit the session ends in failed with error.code = "video_too_large", the credit hold is voided (nothing is charged) and any uploaded bytes are deleted. A URL or Veo source must download at 1 MB/s or faster. A slower host fails the session with error.code = "source_too_slow" and nothing is charged; for those, upload the file with /v1/uploads instead.

Lifecycle

queued  →  processing  →  processed
                       ↘  failed

`status`	Meaning
`queued`	Accepted; waiting for a worker.
`processing`	A worker has the video.
`processed`	Done. `highlights`, `shots`, `players`, `totals` are populated; `cost_cents` is final.
`failed`	Something went wrong; see `error`. The hold is voided — nothing is charged.

A job that never reports back is swept after 24 hours: the session fails with error.code = "timeout", the hold is voided, and you still receive a session.failed event.

The session object

{
  "id": "sess_18234", "object": "session", "created": 1756224000, "status": "processed",
  "group": "grp_412",
  "source": { "type": "veo", "url": "https://app.veo.co/matches/…" },
  "metadata": { "external_match_id": "abc-123" },
  "branding": { "cover": false, "logo": true },
  "teams": { "recording": { "name": "Acme Varsity", "metadata": { "team_id": "lg-t-12" } },
             "opponent":  { "name": "Team 2",       "metadata": {} } },
  "run_version": 1, "duration_seconds": 5412, "cost_cents": 752,

  "highlights": { "object": "list", "total_count": 42, "has_more": false,
                  "url": "/v1/sessions/sess_18234/highlights",
                  "data": [ { "id": "hl_9f2c", "object": "highlight", "shot": "shot_a1b2", "player": "plr_5",
                              "length_seconds": 8.5, "is_lowlight": false,
                              "video": { "default": "…", "horizontal": "…", "1080p": "…", "720p": "…", "480p": "…", "360p": "…", "240p": "…", "144p": "…" },
                              "preview": { "default": "…", "horizontal": "…" } } ] },

  "shots": { "object": "list", "total_count": 118, "has_more": true,
             "url": "/v1/sessions/sess_18234/shots",
             "data": [ { "id": "shot_a1b2", "object": "shot", "index": 7,
                         "start_seconds": 412.0, "end_seconds": 420.5,
                         "made": true, "points": 3, "is_three_point": true, "is_free_throw": false,
                         "location": { "shot_image_normed": [0.42, 0.61] },
                         "excitement_score": 0.87,
                         "players": { "scorer": "plr_5", "assister": "plr_3", "rebounder": null },
                         "highlight": "hl_9f2c" } ] },

  "players": { "object": "list", "total_count": 10, "has_more": false,
               "url": "/v1/sessions/sess_18234/players",
               "data": [ { "id": "plr_5", "object": "player", "name": "Ana", "jersey": "23",
                           "team_id": 1, "team_name": "Acme Varsity",
                           "metadata": { "player_id": "lg-4821" },
                           "stats": { "points": 22, "fg_2pt_att": 9, "fg_2pt_make": 5, "fg_3pt_att": 6, "fg_3pt_make": 4,
                                      "ft_att": 0, "ft_make": 0, "assist": 3, "rebound": 7 } } ] },

  "totals": { "points": 88, "fg_2pt_att": 41, "…": "…" },
  "video": { "url": "…", "preview_url": "…", "1080p": "…", "720p": "…", "360p": "…", "width": 1920, "height": 1080, "fps": 30 },
  "artifacts": { "actions": "…jsonl", "balls": "…jsonl", "hoops": "…jsonl", "clusters": "…jsonl" },
  "error": null
}

Things worth knowing:

Highlights are the product. Each is a cut clip linked to its shot and its player (the scorer).
Embedded lists cap at 100 items. has_more: true means page the url with limit / offset.
Cross-links are ids: shot.highlight → hl_…, shot.players.scorer / highlight.player → plr_… matching players.data[].id. A player’s team_id 1 is teams.recording, 2 is teams.opponent; team_name repeats that side’s name.
A queued, processing or failed session has the same keys with empty lists — never a missing field.
Attribution ignores tags the pipeline marked invalid, using the same rule as the box score, so a shot’s players and a player’s stats always agree.

Idempotency

Send an Idempotency-Key header (any string ≤ 255 chars) on POST /v1/sessions. Replaying the same key with the same body within 24 hours returns the original response with an Idempotent-Replayed: true header; the same key with a different body returns 400 idempotency_key_reused. Concurrent requests with the same key are safe: exactly one session is created, and the others receive its response (or a retryable 409 idempotency_key_in_progress if it hasn’t finished yet). Retrying a 5xx with the same key is also safe — the replay finishes any step the failed attempt left undone. Use your own match id.

Getting started

Core concepts

Integrations

Sources

Request fields

The credit hold

Recording options

Jerseys

Branding

Sending an image

Logo size

What to expect

Branding errors

Rosters

How players are matched

What comes back

Limits

Lifecycle

The session object

Idempotency

​Sources

​Request fields

​The credit hold

​Recording options

​Jerseys

​Branding

​Sending an image

​Logo size

​What to expect

​Branding errors

​Rosters

​How players are matched

​What comes back

​Limits

​Lifecycle

​The session object

​Idempotency

Sources

Request fields

The credit hold

Recording options

Jerseys

Branding

Sending an image

Logo size

What to expect

Branding errors

Rosters

How players are matched

What comes back

Limits

Lifecycle

The session object

Idempotency