Resources¶
OpenAPI is the contract (paths, schemas, status codes). This page is a short map of tags and common entry points.
In Swagger, admin-only operations stay under their resource tag; summaries
are prefixed [Admin].
brands¶
Brand identity (name, hex colors, optional S3 logo).
| Method | Path | Notes |
|---|---|---|
GET |
/api/brands |
List brands; optional q substring search |
POST |
/api/brands |
Multipart create (name, colors, optional logo) |
GET |
/api/brands/{brand_id} |
One brand; logo_url is a stable public object URL |
PATCH |
/api/brands/{brand_id} |
Multipart partial update; optional logo / clear_logo |
DELETE |
/api/brands/{brand_id} |
Deletes row and S3 logo if present |
q is a case-insensitive match on name, primary/secondary color, logo
filename, and id. Logos live under AWS_S3_DEFAULT_BUCKET at
brands/{id}/{filename} (public GetObject on that prefix only).
| Method | Path | Notes |
|---|---|---|
GET |
/api/brands/{brand_id}/question-sponsorships |
List this brand’s question sponsorships; optional repeated match_ids |
POST |
/api/brands/{brand_id}/question-sponsorships |
Bulk assign question sponsorships to matches (replace-by-brand default) |
Body (POST): match_ids, either slots (strategy, optional target,
optional best_effort for period — default true) or random_percent
(1–100; mutually exclusive with non-empty slots), optional
replace_existing_for_brand (default true).
random_percent inserts round(question_max_count × percent / 100) random
slots per match.
Capacity: sponsored_slot_count <= match.question_max_count (409 when
exceeded). Empty slots with replace clears that brand’s question sponsorships.
Whole-match sponsor remains PATCH /api/matches/{id} (sponsor_brand_id).
Match list and detail include sponsor_brand; list also includes
sponsored_question_count, question_issuance_count (non-pivotal), and
pivotal_moment_issuance_count (mutually exclusive Play Following totals).
Detail also includes question_sponsorships.
Open questions include sponsor_brand (issuance stamp) and
match_sponsor_brand (whole-match).
auth¶
| Method | Path | Notes |
|---|---|---|
POST |
/api/auth/register |
Create non-admin local_password user; returns api_key once |
POST |
/api/auth/login |
Username or email + password → new api_key (rotates prior keys); username may be null |
POST |
/api/auth/logout |
Revoke current Bearer key |
users¶
| Method | Path | Notes |
|---|---|---|
GET/PATCH |
/api/users/me |
Self profile (player-allowed patch: email, names, postal, DOB, match_follow_timezone, notify_on_issuance, notify_on_resolve) |
GET |
/api/users/me/points |
All-time + period scored points |
POST |
/api/users/me/devices |
Register/refresh push device (201 create / 200 refresh) |
DELETE |
/api/users/me/devices/{device_id} |
Unregister device on logout (204 idempotent) |
GET/POST |
/api/users |
Admin list (q, is_admin, followed_match_id, sort_by/sort_dir, offset/limit; user_count is total) / create |
GET/PATCH/DELETE |
/api/users/{user_id} |
Admin get / update / soft-deactivate |
Profile fields include match_daily_follow_count (default 3; null =
unrestricted — no quota / answer-follow gate; Live still requires following
to see questions) and IANA match_follow_timezone (match-follow daily quota
window; Live also uses it for the Following “today” slate; blank/null → UTC).
| GET | /api/users/{user_id}/points | Admin points for a user |
| GET | /api/users/{user_id}/question-answers | Admin answer history for a user |
push¶
Admin-only push settings and triage.
| Method | Path | Notes |
|---|---|---|
GET/PATCH |
/api/push-settings |
Gates + message templates (stored_settings) |
POST |
/api/push-settings/reset |
Restore code defaults |
GET |
/api/push-delivery-attempts |
Lookup by user_id or email |
Mobile device registration is under users. Guide: Push notifications.
question-answers¶
Play (Bearer required; scoped to the authenticated user). Admin History uses
GET /api/users/{user_id}/question-answers instead.
| Method | Path | Notes |
|---|---|---|
GET |
/api/question-answers/open |
Unresolved open issuances on matches the caller follows (live statuses or a sliding UTC scheduled window; catch-up / degraded mode). Unions in-game and Match question (kind) |
PUT |
/api/question-answers |
Upsert answer while window is open (in-game) or until lock (Match question 410); restricted users must follow the match (403 otherwise) |
GET |
/api/question-answers |
History for the caller (unions both kinds). With limit, locked pending Match answers are listed first and do not consume the limit |
Open rows include sponsor_brand (issuance stamp) and match_sponsor_brand.
History list items include the same sponsor fields.
Live push: WS /api/play/stream?api_key= (not in OpenAPI). Full client
contract: Live play client.
See Getting started.
user-feedback¶
Generic player feedback collection. The first subjects are resolved question-answers. Form contract and mobile how-to: Report this (user feedback).
| Method | Path | Notes |
|---|---|---|
GET |
/api/user-feedback/form |
No auth. Subject types (with history kind) and per-type topics; description_max_length |
POST |
/api/user-feedback |
Player-allowed write. Body is subject_type + subject_id + topic + optional description |
GET |
/api/user-feedback |
Player: own rows. Admin: optional user_id, match_id, created_from/created_to, subject_type, topic. Page is feedback; feedback_count is the filtered total |
GET |
/api/user-feedback/{id} |
Owner or admin |
leagues¶
League defaults for question caps, period distribution, points, and answer window.
| Method | Path | Notes |
|---|---|---|
GET |
/api/leagues |
List all leagues with defaults |
GET |
/api/leagues/{league_id} |
One league by id |
PATCH |
/api/leagues/{league_id} |
Update question defaults (partial) |
matches¶
Schedule, overrides, test clone/replay, listener start/stop.
| Method | Path | Notes |
|---|---|---|
GET |
/api/matches |
Filter by league, UTC scheduled_from/scheduled_to, status, is_test, followed (auth required; followed=true skips the default UTC-today clamp) |
GET |
/api/matches/{match_id}/question-issuances |
Auth required; in-game issuance history (not Match questions). Admins get open+resolved; non-admins (mobile/player) get resolved only. Live questions: /question-answers/open + play WS |
POST/DELETE |
/api/matches/{match_id}/follow |
Follow / unfollow (player); daily non-test quota; new follow blocked when closed; unfollow after start does not refund today's slot (re-follow reactivates; test matches always refund) |
PATCH |
/api/matches/{match_id} |
Overrides / auto_dispatch_listener / test status |
DELETE |
/api/matches/{match_id} |
Test matches only |
POST |
/api/matches/{match_id}/clone |
CLOSED → is_test + enqueue srsim listener; records created_by_user_id; auto-follows creator (force); copies/overrides question settings, sponsor_brand_id, and question_sponsorships |
POST |
/api/matches/{match_id}/start-listener |
Enqueue for is_test |
POST |
/api/matches/{match_id}/stop-listener |
Revoke / close open rows |
Scheduled filters use UTC instants on Match.scheduled
(scheduled_from inclusive, scheduled_to exclusive). When omitted,
GET /api/matches defaults to UTC calendar today. Clients (admin, mobile)
convert local calendar days to those bounds before calling.
Distinguish internal match id (Match.id) from Sportradar match id
(Match.sr_id). Clone/start are unavailable in the main environment.
Related: Match listener startup, SRSim parameters.
match-listeners¶
Lifecycle rows and artifacts.
| Method | Path | Notes |
|---|---|---|
GET |
/api/match-listeners |
Grouped by match for league + UTC scheduled range |
GET |
/api/match-listeners/{listener_id}/log |
Text log JSON payload |
GET |
/api/match-listeners/{listener_id}/log/download |
File download |
GET |
/api/match-listeners/{listener_id}/events/download |
Event recording JSON |
Related: Match Listeners admin.
question-definitions¶
Authoring and preview (DB-backed; not JSON seed files).
| Method | Path | Notes |
|---|---|---|
GET |
/api/question-definitions/sample-catalog |
Sample-feed field browser |
POST |
/api/question-definitions/preview |
Render templates against a sample event |
GET/POST |
/api/question-definitions |
List / create (league query; list also supports include_inactive, q, is_pivotal_moment, created_from/created_to, updated_from/updated_to) |
GET/PUT |
/api/question-definitions/{definition_id} |
Read / full update |
POST |
.../clone, .../archive, .../activate |
Lifecycle actions |
Related: Question definitions guide, League / event / store_state.
match-question-definitions¶
Match question (pre-game) definition authoring.
| Method | Path | Notes |
|---|---|---|
GET/POST |
/api/match-question-definitions |
List / create (league query) |
GET/PUT |
/api/match-question-definitions/{definition_id} |
Read / full update |
POST |
.../clone, .../archive, .../activate |
Lifecycle actions |
DELETE |
/api/match-question-definitions/{definition_id} |
Hard-delete when unused |
Related: Match question issuance & resolution.