Skip to main content
The Hooper API turns raw game footage into structured basketball data. You submit a video — an upload, a public URL, or a Veo link — and Hooper’s vision pipeline returns:

Highlights

A clip for every shot, in up to seven renditions plus horizontal cuts and previews.

Shots

Timing, outcome, points, court location, who scored / assisted / rebounded.

Players

The roster with a per-player box score and team totals.

​
How it works

1

Submit a video

POST /v1/sessions with a source. A credit hold is placed and the job is queued. You get a session back immediately in queued state.
2

Get notified

When processing finishes, Hooper POSTs a signed session.processed (or session.failed) event to your webhook endpoint. The event carries the full session — highlights included — so there is nothing to fetch.
3

Use the data

Every session, highlight, shot and player has a stable prefixed id (sess_, hl_, shot_, plr_) and cross-links to the others.

​
Conventions

  • Base URL https://api.hooper.gg, all paths under /v1.
  • Auth Authorization: Bearer hk_prod_… — see Authentication.
  • Ids are opaque prefixed strings. Every object carries object and created (Unix seconds).
  • Lists — top-level or embedded — are always { "object": "list", "data": [...], "has_more": bool, "total_count": n }.
  • Money is integer cents. Time is Unix seconds.
  • Errors are { "error": { "type", "code", "message", "param" } } — see Errors.
  • Every response carries a Request-Id header. Quote it when you contact support.

​
Environments

Keys are tagged with the environment that minted them: hk_prod_… works against production, hk_stg_… against staging. Sending a key to the wrong environment returns 401 with code: "wrong_environment" so the mistake is obvious.