{ "openapi": "3.1.0", "info": { "title": "D-Sports API", "description": "Public API for the D-Sports fan engagement platform (PWA backend). Most endpoints require Clerk Bearer authentication.", "version": "1.0.0" }, "servers": [ { "url": "https://app.d-sports.org", "description": "Production" }, { "url": "http://localhost:3004", "description": "Local development" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Auth", "description": "Authentication and token exchange" }, { "name": "Logout", "description": "Session logout" }, { "name": "Mobile auth", "description": "OAuth flow for native apps" }, { "name": "Teams", "description": "Teams list and follow/unfollow" }, { "name": "Leaderboard", "description": "Leaderboards, seasons, winners, stats" }, { "name": "Locker room", "description": "Social feed posts, comments, reactions" }, { "name": "Packs", "description": "Packs list, purchase, open" }, { "name": "User", "description": "Profile, onboarding, follow, search, privacy" }, { "name": "Quests", "description": "Quests and progress" }, { "name": "Rewards", "description": "Rewards claim and redeem" }, { "name": "Wallets", "description": "Wallets and coin prices" }, { "name": "Checkout", "description": "Crypto and D-Sports Cash checkout" }, { "name": "D-Sports Cash", "description": "D-Sports Cash balance" }, { "name": "Dashboard", "description": "Dashboard stats and balance" }, { "name": "Products", "description": "Products and packs catalog" }, { "name": "Webhooks", "description": "RevenueCat webhook" }, { "name": "Misc", "description": "Image proxy, crypto prices, upload, feedback" }, { "name": "Auth and onboarding", "description": "Domain grouping for auth, profile, onboarding, and identity flows" }, { "name": "Social and locker room", "description": "Domain grouping for social feed, follows, and community interactions" }, { "name": "Gamification", "description": "Domain grouping for quests, leaderboards, points-facing outcomes, and rewards" }, { "name": "Commerce and purchases", "description": "Domain grouping for checkout, cash balance, webhooks, and store purchase flows" }, { "name": "Collectibles and packs", "description": "Domain grouping for pack lifecycle and collectible inventory" }, { "name": "Wallet and web3", "description": "Domain grouping for wallet and crypto-support operations" }, { "name": "Moderation and reporting", "description": "Domain grouping for user-facing report submission and moderation-adjacent endpoints" }, { "name": "Platform and infrastructure", "description": "Domain grouping for utility, infrastructure, and platform support endpoints" }, { "name": "Rep", "description": "Fan / Club / Player / Direct Rep earn, breakdown, and ledger" }, { "name": "Engage", "description": "Engage-domain Rep and related mobile contracts" }, { "name": "Admin", "description": "Staff-only admin operations" }, { "name": "Binders", "description": "Digital binder inventory, PIN, and card transfer" }, { "name": "Games", "description": "Team mini-game catalog and play routes" }, { "name": "Game Engine", "description": "Engage native catalog and server-authoritative daily session lifecycle" }, { "name": "Events", "description": "Game schedule, Game Center, chat, presence, and ratings" }, { "name": "Notifications", "description": "Authenticated in-app inbox" }, { "name": "Config", "description": "Public catalogs and support matrices" }, { "name": "Discovery", "description": "Suggested fans and teams" }, { "name": "Leagues", "description": "League metadata and branding" }, { "name": "Marketplace", "description": "Listings, bids, offers, cart, and shop merchandising" }, { "name": "KYC", "description": "Identity verification session helpers" }, { "name": "Passes", "description": "Apple Wallet and Google Wallet pass issuance" }, { "name": "App Clips", "description": "Public iOS App Clip previews" } ], "paths": { "/api/admin/users": { "get": { "tags": [ "Admin" ], "summary": "List staff Fans search results", "description": "Requires Clerk authentication and isAdmin (admin or superadmin). Moderators, club-only staff and regular fans receive 403; anonymous callers receive 401. Returns the existing staff Fans list with additive integer dsportsCash, including zero, without ledger history. Consumed by d-sports-engage-native#1239. Existing search, sorting and pagination are unchanged.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number; values below 1 are clamped to 1.", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page; clamped to 1 through 100.", "schema": { "type": "integer", "default": 20 } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match across email, name or handle.", "schema": { "type": "string", "default": "" } }, { "name": "sortBy", "in": "query", "required": false, "description": "User scalar field used for sorting; invalid fields produce INTERNAL_ERROR.", "schema": { "type": "string", "default": "createdAt" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Only asc selects ascending order; all other values use desc.", "schema": { "type": "string", "default": "desc" } } ], "responses": { "200": { "description": "Paginated Fans with balances visible only to platform admins.", "headers": { "Cache-Control": { "description": "Personalized staff response must not be cached.", "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "users", "pagination" ], "properties": { "users": { "type": "array", "items": { "type": "object", "required": [ "id", "email", "name", "handle", "profileUrl", "profileUrlThumbhash", "createdAt", "onboardingComplete", "dsportsCash", "roles", "labels", "_count", "isAdmin", "isSuperAdmin", "isModerator" ], "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "profileUrl": { "type": "string" }, "profileUrlThumbhash": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "onboardingComplete": { "type": "boolean" }, "dsportsCash": { "type": "integer", "description": "Current User.dsportsCash balance; zero is returned explicitly.", "examples": [ 150, 0 ] }, "roles": { "type": "array", "description": "Combined role strings and display label strings.", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string" } } } }, "_count": { "type": "object", "required": [ "followers", "following" ], "properties": { "followers": { "type": "integer" }, "following": { "type": "integer" } } }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" }, "isModerator": { "type": "boolean" } } } }, "pagination": { "type": "object", "required": [ "page", "limit", "totalCount", "totalPages", "hasMore" ], "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalCount": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } } } } } } }, "401": { "description": "Missing Clerk authentication (UNAUTHORIZED).", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "code": { "const": "UNAUTHORIZED" } } } } } }, "403": { "description": "Not an admin or superadmin (FORBIDDEN), including moderators and club-only staff.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "code": { "const": "FORBIDDEN" } } } } } }, "500": { "description": "Failed to fetch fans (INTERNAL_ERROR); logged through logger.error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "code": { "const": "INTERNAL_ERROR" } } } } } } } } }, "/api/admin/content/{slug}/locales/{locale}": { "get": { "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "fr-CH", "it-IT" ] } } ], "operationId": "getCopyLocale", "summary": "Read authored content locale draft and publication", "description": "Existing parent required. Exact case-sensitive fr-CH/it-IT only. English/base admin response shapes are unchanged.", "responses": { "200": { "description": "{ success: true, data: variant row } — JSON draft/published, draftReviewed, reviewedAt/By, publishedReviewedAt/By, draftUpdatedBy, publishedAt/By, version, timestamps." }, "400": { "description": "Invalid slug, exact locale, complete snapshot or review state" }, "401": { "description": "Not authenticated" }, "403": { "description": "Platform moderator/admin/superadmin required; team scope is insufficient" }, "404": { "description": "Parent or locale not found" }, "500": { "description": "Database/internal error; mutations never silently fall back" } } }, "put": { "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "fr-CH", "it-IT" ] } } ], "operationId": "saveCopyLocale", "summary": "Replace complete authored content locale draft", "description": "Human-authored content only, never machine-translated. Every save resets draft review unless the saving moderator attests reviewed: true. Live snapshot and published review provenance are unchanged. Parent row is locked.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "content" ], "properties": { "content": { "$ref": "#/components/schemas/ApprovedCopyLocaleContent" }, "reviewed": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "{ success: true, data: variant row } — JSON draft/published, draftReviewed, reviewedAt/By, publishedReviewedAt/By, draftUpdatedBy, publishedAt/By, version, timestamps." }, "400": { "description": "Invalid slug, exact locale, complete snapshot or review state" }, "401": { "description": "Not authenticated" }, "403": { "description": "Platform moderator/admin/superadmin required; team scope is insufficient" }, "404": { "description": "Parent content not found (an absent locale is created by PUT; clearing an absent locale succeeds)." }, "500": { "description": "Database/internal error; mutations never silently fall back" } } }, "delete": { "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "fr-CH", "it-IT" ] } } ], "operationId": "clearCopyLocale", "summary": "Clear one authored content locale", "description": "Idempotent for an existing parent. Only selected locale removed; next uncached read falls back to English. Existing CDN 300s + 3600s SWR can still serve prior publication.", "responses": { "200": { "description": "{ success: true, data: { locale, cleared: true } }" }, "400": { "description": "Invalid slug, exact locale, complete snapshot or review state" }, "401": { "description": "Not authenticated" }, "403": { "description": "Platform moderator/admin/superadmin required; team scope is insufficient" }, "404": { "description": "Parent content not found (an absent locale is created by PUT; clearing an absent locale succeeds)." }, "500": { "description": "Database/internal error; mutations never silently fall back" } } } }, "/api/admin/content/{slug}/locales/{locale}/publish": { "post": { "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "fr-CH", "it-IT" ] } } ], "operationId": "publishCopyLocale", "summary": "Publish reviewed authored content locale", "description": "Parent FOR UPDATE transaction validates draft and review provenance, copies the complete snapshot + independent published review provenance, increments locale version and stamps publisher/time. Unreviewed drafts return 400. Base publication still gates fan reads.", "responses": { "200": { "description": "{ success: true, data: variant row } — JSON draft/published, draftReviewed, reviewedAt/By, publishedReviewedAt/By, draftUpdatedBy, publishedAt/By, version, timestamps." }, "400": { "description": "Invalid slug, exact locale, complete snapshot or review state" }, "401": { "description": "Not authenticated" }, "403": { "description": "Platform moderator/admin/superadmin required; team scope is insufficient" }, "404": { "description": "Parent or locale not found" }, "500": { "description": "Database/internal error; mutations never silently fall back" } } } }, "/api/admin/changelog/{slug}/locales/{locale}": { "get": { "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "fr-CH", "it-IT" ] } } ], "operationId": "getChangelogLocale", "summary": "Read authored changelog locale draft and publication", "description": "Existing parent required. Exact case-sensitive fr-CH/it-IT only. English/base admin response shapes are unchanged.", "responses": { "200": { "description": "{ success: true, data: variant row } — JSON draft/published, draftReviewed, reviewedAt/By, publishedReviewedAt/By, draftUpdatedBy, publishedAt/By, version, timestamps." }, "400": { "description": "Invalid slug, exact locale, complete snapshot or review state" }, "401": { "description": "Not authenticated" }, "403": { "description": "Platform moderator/admin/superadmin required; team scope is insufficient" }, "404": { "description": "Parent or locale not found" }, "500": { "description": "Database/internal error; mutations never silently fall back" } } }, "put": { "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "fr-CH", "it-IT" ] } } ], "operationId": "saveChangelogLocale", "summary": "Replace complete authored changelog locale draft", "description": "Human-authored content only, never machine-translated. Every save resets draft review unless the saving moderator attests reviewed: true. Live snapshot and published review provenance are unchanged. Parent row is locked.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "content" ], "properties": { "content": { "$ref": "#/components/schemas/ChangelogLocaleContent" }, "reviewed": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "{ success: true, data: variant row } — JSON draft/published, draftReviewed, reviewedAt/By, publishedReviewedAt/By, draftUpdatedBy, publishedAt/By, version, timestamps." }, "400": { "description": "Invalid slug, exact locale, complete snapshot or review state" }, "401": { "description": "Not authenticated" }, "403": { "description": "Platform moderator/admin/superadmin required; team scope is insufficient" }, "404": { "description": "Parent content not found (an absent locale is created by PUT; clearing an absent locale succeeds)." }, "500": { "description": "Database/internal error; mutations never silently fall back" } } }, "delete": { "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "fr-CH", "it-IT" ] } } ], "operationId": "clearChangelogLocale", "summary": "Clear one authored changelog locale", "description": "Idempotent for an existing parent. Only selected locale removed; next uncached read falls back to English. Existing CDN 300s + 3600s SWR can still serve prior publication.", "responses": { "200": { "description": "{ success: true, data: { locale, cleared: true } }" }, "400": { "description": "Invalid slug, exact locale, complete snapshot or review state" }, "401": { "description": "Not authenticated" }, "403": { "description": "Platform moderator/admin/superadmin required; team scope is insufficient" }, "404": { "description": "Parent content not found (an absent locale is created by PUT; clearing an absent locale succeeds)." }, "500": { "description": "Database/internal error; mutations never silently fall back" } } } }, "/api/admin/changelog/{slug}/locales/{locale}/publish": { "post": { "tags": [ "Admin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, { "name": "locale", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "fr-CH", "it-IT" ] } } ], "operationId": "publishChangelogLocale", "summary": "Publish reviewed authored changelog locale", "description": "Parent FOR UPDATE transaction validates draft and review provenance, copies the complete snapshot + independent published review provenance, increments locale version and stamps publisher/time. Unreviewed drafts return 400. Base publication still gates fan reads.", "responses": { "200": { "description": "{ success: true, data: variant row } — JSON draft/published, draftReviewed, reviewedAt/By, publishedReviewedAt/By, draftUpdatedBy, publishedAt/By, version, timestamps." }, "400": { "description": "Invalid slug, exact locale, complete snapshot or review state" }, "401": { "description": "Not authenticated" }, "403": { "description": "Platform moderator/admin/superadmin required; team scope is insufficient" }, "404": { "description": "Parent or locale not found" }, "500": { "description": "Database/internal error; mutations never silently fall back" } } } }, "/api/accessibility": { "get": { "tags": [ "Config" ], "summary": "Accessibility support matrix", "description": "Public Apple Nutrition Label-style feature support matrix for native and marketing.", "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/admin/users/{userId}/rep": { "post": { "tags": [ "Admin", "Rep" ], "summary": "Grant D-Sports Direct Rep to a user", "description": "isAdmin only. Body: { amount: integer 1–100000, reason?: string max 200, idempotencyKey?: string }. Retries: send an Idempotency-Key header (or body idempotencyKey; the header wins), 1–128 of letters, digits, '_', '-', ':' or '.'. The ledger keys the grant per admin, so a retry returns the original entry with alreadyRecorded: true and grants nothing new; reusing a key with a different amount is 409 IDEMPOTENCY_KEY_REUSED. Without a key each POST is a new grant.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{1,128}$" }, "description": "Client retry key, scoped to the calling admin." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "reason": { "type": "string", "maxLength": 200 }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{1,128}$", "description": "Same as the Idempotency-Key header; used only when the header is absent." } } } } } }, "responses": { "200": { "description": "{ userId, amount, reason, entryId, alreadyRecorded } — alreadyRecorded is true when an idempotency key replayed an earlier grant." }, "400": { "description": "Invalid amount, reason or idempotency key" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin access required" }, "404": { "description": "User not found" }, "409": { "description": "IDEMPOTENCY_KEY_REUSED — the key was already used for a different amount" }, "500": { "description": "Failed to record Direct Rep grant" } } } }, "/api/admin/content": { "get": { "tags": [ "Admin" ], "operationId": "listAdminContent", "summary": "List approved copy slugs", "description": "Platform moderator/admin only (#998). Returns `{ copies: AdminCopy[] }`, most recently edited first (max 100), where `AdminCopy` is the public payload plus `draft: { blocks, updatedBy }` and `publishedBy`. No team scope — approved copy is global.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { copies } }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" } } }, "post": { "tags": [ "Admin" ], "operationId": "createAdminContentDraft", "summary": "Create an approved-copy slug from a draft", "description": "Platform moderator/admin only (#998). Upsert semantics: creates the slug when absent and saves the draft block, or re-saves the draft of an existing slug. Publishing is a separate `POST /api/admin/content/{slug}/publish`, so a half-written edit never reaches clients. Body: `{ slug, title?, body?, bullets? }` with at least one of the three content fields. `slug` must be lowercase words separated by hyphens.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 }, "title": { "type": "string", "maxLength": 200 }, "body": { "type": "string", "maxLength": 8000 }, "bullets": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 500 } } } } } } }, "responses": { "200": { "description": "{ success, data: AdminCopy } — an existing draft was re-saved." }, "201": { "description": "{ success, data: AdminCopy } — the slug was created." }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" } } } }, "/api/admin/content/{slug}": { "get": { "tags": [ "Admin" ], "operationId": "getAdminContent", "summary": "Get approved copy with draft and published blocks", "description": "Platform moderator/admin only (#998). `AdminCopy` = public payload plus `draft: { blocks, updatedBy }` and `publishedBy`, so an editor sees what is live while drafting the next revision. An unpublished slug reports `version: 0` and an empty `blocks`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: AdminCopy }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" }, "404": { "description": "{ success: false, error, code: \"NOT_FOUND\" }" } } }, "put": { "tags": [ "Admin" ], "operationId": "saveAdminContentDraft", "summary": "Save the draft block for a slug", "description": "Platform moderator/admin only (#998). Partial write: omitted fields keep their stored value, and `bullets` is trimmed with blanks dropped. Nothing reaches `GET /api/content/{slug}` until `POST /api/admin/content/{slug}/publish`. `PATCH` is an alias of `PUT`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "body": { "type": "string", "maxLength": 8000 }, "bullets": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 500 } } } } } } }, "responses": { "200": { "description": "{ success, data: AdminCopy }" }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" } } }, "patch": { "tags": [ "Admin" ], "operationId": "patchAdminContentDraft", "summary": "Alias of PUT — save the draft block for a slug", "description": "Same handler and body as `PUT /api/admin/content/{slug}` (#998).", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "body": { "type": "string", "maxLength": 8000 }, "bullets": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 500 } } } } } } }, "responses": { "200": { "description": "{ success, data: AdminCopy }" }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" } } } }, "/api/admin/content/{slug}/publish": { "post": { "tags": [ "Admin" ], "operationId": "publishAdminContent", "summary": "Publish the current draft for a slug", "description": "Platform moderator/admin only (#998). Copies the draft onto the published block, bumps `version` by one and stamps `publishedAt`/`publishedBy` — which is what changes the public `GET /api/content/{slug}` payload and its `ETag`. Refused with `VALIDATION_ERROR` when the draft has a blank title; 404 when the slug does not exist.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: AdminCopy }" }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" }, "404": { "description": "{ success: false, error, code: \"NOT_FOUND\" }" } } } }, "/api/admin/packs": { "get": { "tags": [ "Admin", "Packs" ], "summary": "List a team's packs with contents (admin; pack-test source)", "description": "Requires canAccessTeam: platform admin/superadmin, or any TeamAdmin role on the team (owner, editor, viewer). `teamId` is a team id or slug. Always includes contents (`includeContents: true`) with the full collectible, plus `maxReveal`, so web PackTesting and native (engage-native#1248) can run weightedRandomSelect(pack.contents, pack.maxReveal) locally. There is no pack-test start/stop session API: simulated opens are never sent to or stored by the server. Newest first, no pagination. `archived=true` lists archived packs only (status archived, ordered by updatedAt desc) with the same contents shape. Staging JSON capture is deferred; the example is a fixture, not a live capture.", "parameters": [ { "name": "teamId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Team id or slug." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by pack status, e.g. active or draft." }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true lists archived packs only, with the same contents shape." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success: true, data: Pack[] }", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "description": "Pack row with every scalar column plus contents. Only the fields below are the pack-test contract; other Pack scalars are returned too.", "required": [ "id", "name", "maxReveal", "contents" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "maxReveal": { "type": "integer", "description": "Cards revealed per open. Default 3." }, "contents": { "type": "array", "items": { "type": "object", "description": "PackCollectible row: one collectible in the pack's draw pool.", "required": [ "id", "packId", "collectibleId", "quantity", "weight", "collectible" ], "properties": { "id": { "type": "string" }, "packId": { "type": "string" }, "collectibleId": { "type": "string" }, "quantity": { "type": "integer", "description": "Copies per draw of this collectible. Default 1." }, "weight": { "type": "integer", "description": "Relative draw weight. Default 100. Used by the client-side weightedRandomSelect simulation." }, "collectible": { "type": "object", "description": "Full Collectible row (every scalar column), not a narrowed select.", "required": [ "id", "name", "description", "image", "rarity" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "rarity": { "type": "string", "enum": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC" ] } }, "additionalProperties": true } } } } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "pack_1", "name": "Starter", "maxReveal": 3, "contents": [ { "id": "pc_1", "packId": "pack_1", "collectibleId": "c1", "quantity": 1, "weight": 10, "collectible": { "id": "c1", "name": "Example Skater", "description": "Example", "image": "https://example.test/c1.png", "rarity": "COMMON" } } ] } ] } } } }, "400": { "description": "{ success: false, error: \"Team ID required\" }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "500": { "description": "{ success: false, error: \"Failed to list packs\" } (\"Failed to list archived packs\" with archived=true)" } } } }, "/api/admin/packs/upload-glb-template": { "post": { "tags": [ "Admin", "Packs" ], "summary": "Mint a signed upload URL for a pack-opening template GLB", "description": "Team templates (canManageTeam) land at teams/{teamId}/templates/. Global templates require scope \"global\" and an admin, and land at templates/. Omitting teamId without scope global is rejected. The file never passes through this route: PUT it to signedUrl, then POST /api/admin/packs/confirm-upload with kind \"glb-template\" before persisting modelUrl and glbTemplateVersion. Validation: .glb, MIME model/gltf-binary or application/octet-stream, 1 byte–10MB, magicBytes start with glTF. Header, material slots, and extensions are checked on confirm.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fileName", "fileSize", "mimeType", "magicBytes" ], "properties": { "teamId": { "type": "string", "description": "Team id or slug. Required unless scope is global." }, "scope": { "type": "string", "enum": [ "team", "global" ] }, "fileName": { "type": "string", "pattern": "\\.[gG][lL][bB]$" }, "fileSize": { "type": "integer", "minimum": 1, "maximum": 10485760 }, "mimeType": { "type": "string", "enum": [ "model/gltf-binary", "application/octet-stream" ] }, "magicBytes": { "type": "string", "format": "byte", "description": "Base64 of the file's first ≥4 bytes." } } } } } }, "responses": { "200": { "description": "{ signedUrl, token, path, publicUrl, bucket, contentType }", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "signedUrl", "token", "path", "publicUrl", "bucket", "contentType" ], "properties": { "signedUrl": { "type": "string" }, "token": { "type": "string" }, "path": { "type": "string", "description": "Storage key under teams/{teamId}/templates/ or templates/, ending in .glb." }, "publicUrl": { "type": "string" }, "bucket": { "type": "string", "enum": [ "pack-assets" ] }, "contentType": { "type": "string", "enum": [ "model/gltf-binary", "application/octet-stream" ] } } } } } } } }, "400": { "description": "VALIDATION_ERROR — bad extension, MIME, size (max 10MB), or magic bytes; or missing teamId" }, "401": { "description": "Authentication required" }, "403": { "description": "FORBIDDEN — caller cannot manage the team" }, "500": { "description": "Signed URL mint failed" } } } }, "/api/admin/packs/upload-pack-art": { "post": { "tags": [ "Admin", "Packs" ], "summary": "Mint a signed upload URL for pack or card-case art", "description": "Team managers only (canManageTeam). Staging key teams/{teamId}/pack-art/{front|back|card-case|card-back}/staging/. Confirm with the same kind. Pack front/back require glbTemplateVersion 0 or 2: version 0 contains the image in the UV window on a 1024x1536 canvas, and version 2 fills a 1104x1536 canvas. Card-case and card-back ignore glbTemplateVersion; confirm covers a 1200x1680 canvas. The stored object is immutable.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId", "kind", "fileName", "fileSize", "mimeType", "magicBytes" ], "properties": { "teamId": { "type": "string" }, "kind": { "type": "string", "enum": [ "pack-art-front", "pack-art-back", "card-case-art", "card-back" ] }, "fileName": { "type": "string" }, "fileSize": { "type": "integer", "minimum": 1, "maximum": 15728640 }, "mimeType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "magicBytes": { "type": "string", "format": "byte" }, "glbTemplateVersion": { "type": "integer", "enum": [ 0, 2 ], "description": "Required for pack-art-front and pack-art-back. 0 selects the UV window on a 1024x1536 canvas. 2 selects the full-bleed 1104x1536 canvas. Omitted or any other integer is rejected for those kinds. card-case-art and card-back ignore this property." } } } } } }, "responses": { "200": { "description": "{ signedUrl, token, path, publicUrl, bucket, contentType }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "Authentication required" }, "403": { "description": "FORBIDDEN" } } } }, "/api/admin/packs/confirm-upload": { "post": { "tags": [ "Admin", "Packs" ], "summary": "Confirm a signed pack / collectible asset upload", "description": "Team managers only, except a global template at templates/ which requires an admin. Revalidates the stored object: path prefix, size equals expectedSize, and magic. kind glb-template downloads the object (max 10MB), rejects text/html, Draco, and KTX2, accepts EXT_meshopt_compression, and returns glbTemplateVersion, glbIdleClip, glbMinScene (3 for meshopt, else null) and material slots. Version 0 is pack FRONT/BACK and requires KHR_texture_transform on both (UV window on a 1024x1536 canvas). Version 1 is the card case (TeamArt/CardBack). Version 2 is the combined opening (FRONT, BACK, TeamArt, CardBack) with a full-bleed 1104x1536 pack-face canvas and no texture transform. Declaring version 0 for a file that satisfies version 2 is rejected. Pack art kinds contain into the version-0 window or the version-2 1104x1536 canvas. Card-case art kinds cover a 1200x1680 canvas. glbTemplateVersion is never defaulted. glbIdleClip is null unless it is CaseIdle on version 2.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "kind", "expectedSize" ], "properties": { "teamId": { "type": "string" }, "path": { "type": "string" }, "kind": { "type": "string", "enum": [ "model", "video", "artwork", "collectible-model", "collectible-video", "glb-template", "pack-art-front", "pack-art-back", "card-case-art", "card-back" ] }, "expectedSize": { "type": "integer", "minimum": 1 }, "publicUrl": { "type": "string", "description": "Echoed back when valid." }, "glbTemplateVersion": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "kind glb-template: omitted detects the contract. Never defaulted. 0 is pack FRONT/BACK with KHR_texture_transform. 2 is the combined opening and cannot be declared as 0. Pack art kinds: 0 selects the 1024x1536 UV window; 2 selects the full-bleed 1104x1536 canvas." }, "glbIdleClip": { "type": [ "string", "null" ], "description": "kind glb-template only. Null or omitted means idle is off. The only other value is CaseIdle, and only when glbTemplateVersion is 2." } } } } } }, "responses": { "200": { "description": "{ path, kind, size, publicUrl, bucket, confirmed, glbTemplateVersion?, glbIdleClip?, glbMinScene?, templateKind?, slots? }", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "path", "kind", "size", "publicUrl", "bucket", "confirmed" ], "properties": { "path": { "type": "string" }, "kind": { "type": "string" }, "size": { "type": "integer" }, "publicUrl": { "type": "string" }, "bucket": { "type": "string" }, "confirmed": { "type": "boolean", "enum": [ true ] }, "glbTemplateVersion": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Present for kind glb-template. 0 is FRONT/BACK with KHR_texture_transform (1024x1536 UV window). 2 is the combined opening (full-bleed 1104x1536 pack faces)." }, "glbIdleClip": { "type": [ "string", "null" ], "description": "Present for kind glb-template. Null means idle is off. CaseIdle is valid only when glbTemplateVersion is 2." }, "glbMinScene": { "type": [ "integer", "null" ], "description": "Present for kind glb-template. 3 means EXT_meshopt_compression; null means no scene-level requirement." }, "templateKind": { "type": "string", "enum": [ "pack", "card-case" ] }, "slots": { "type": "array", "items": { "type": "object", "required": [ "role", "material" ], "properties": { "role": { "type": "string" }, "material": { "type": "string" } } } } } } } } } } }, "400": { "description": "VALIDATION_ERROR — path outside the team prefix, size mismatch / over cap, bad magic, unexpected content-type, or unknown glbTemplateVersion" }, "401": { "description": "Authentication required" }, "403": { "description": "FORBIDDEN — caller cannot manage the team" }, "404": { "description": "NOT_FOUND — uploaded object not in storage" } } } }, "/api/auth/native-token": { "post": { "tags": [ "Auth" ], "summary": "Get native sign-in token", "description": "Generates a sign-in token for the authenticated user. Used by native app: pass Bearer token, get ticket for WebView sign-in.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ ticket, expiresAt }" }, "401": { "description": "No authorization token provided" } } } }, "/api/auth/validate": { "post": { "tags": [ "Auth" ], "summary": "Validate token", "description": "Validates the Bearer token.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ valid, ... }" }, "401": { "description": "Invalid or missing token" } } } }, "/api/binders": { "get": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "List authenticated user's binders", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "walletAddress", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ binders }" }, "403": { "description": "WALLET_NOT_LINKED — ?walletAddress names a wallet not linked to the fan." } } }, "post": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "Create a binder", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "sport", "walletAddress" ], "properties": { "name": { "type": "string" }, "sport": { "type": "string" }, "walletAddress": { "type": "string" }, "pin": { "type": "string", "description": "Binder PIN, not the wallet PIN" }, "coverImage": { "type": "string" }, "coverStyle": { "type": [ "object", "null" ], "description": "Built cover design, validated and stored exactly as on PATCH /api/binders/{id}. Omit or null for a classic cover.", "properties": { "v": { "type": "integer", "const": 1 }, "material": { "type": "string", "enum": [ "leather", "pebble", "linen", "carbon", "metal", "printed" ] }, "colour": { "type": "string", "enum": [ "navy", "royal", "oxblood", "forest", "sand", "ivory", "black", "graphite" ] }, "foil": { "type": "string", "enum": [ "gold", "silver", "rose", "holo", "deboss" ] }, "hardware": { "type": "string", "enum": [ "gold", "chrome", "gunmetal", "none" ] }, "strap": { "type": "boolean" }, "label": { "type": "boolean" }, "nameStamp": { "type": "string", "enum": [ "front", "spine", "both", "none" ] }, "emblem": { "type": [ "object", "null" ], "properties": { "shape": { "type": "string", "enum": [ "circle", "square", "rect" ] }, "source": { "type": "object", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "team" }, "teamId": { "type": "string" }, "name": { "type": "string", "description": "Response only: the team's name (ignored on input)." }, "uri": { "type": "string", "description": "Response only: the team's logo, else its league's (ignored on input)." } }, "required": [ "kind", "teamId" ] }, { "type": "object", "properties": { "kind": { "const": "photo" }, "uri": { "type": "string" } }, "required": [ "kind", "uri" ] } ] } }, "required": [ "shape", "source" ] }, "art": { "type": [ "string", "null" ], "description": "Printed art: an owned https image URL, or a cover token (mock-cover: or a catalog id)." } }, "required": [ "v", "material", "colour", "foil", "hardware", "strap", "label", "nameStamp", "emblem" ] } } } } } }, "responses": { "200": { "description": "{ binder }" }, "400": { "description": "VALIDATION_ERROR" } } } }, "/api/binders/{id}": { "get": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "Get binder contents grouped by shelf", "description": "Data: { binder, shelves }. Each shelf card adds serial: CardSerial | null — the lowest serial among the owner's copies of that collectible (ties: earliest mint); null when no copy has a recorded serial. Each shelf card adds player: CardPlayer | null at the top level of the card (next to serial): the roster player linked to that collectible; null when none is linked. Each shelf card adds lockedBy and lockedQuantity (BinderLockedCard): the listing/offer lock on the owner's holdings of that collectible in the binder's wallet. lockedQuantity is a reserved copy count capped at the card's quantity, not the inventory reads' 0 = whole row encoding. A PIN-protected binder without a valid token returns metadata only, with no lock data. Binder metadata includes coverStyle (built cover design, or null for classic).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ binder, shelves }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "shelves": { "type": "object", "description": "Cards keyed by shelf.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/BinderLockedCard" } } } } } } } } } } } }, "patch": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "Rename binder, update cover, or set built cover style", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "coverImage": { "type": [ "string", "null" ] }, "coverStyle": { "type": [ "object", "null" ], "description": "Built cover design (v1: material, colour, foil, hardware, strap, label, nameStamp, emblem, art). Null clears to the classic cover. Unknown keys are dropped. Photo emblem uri must be an https binder-cover blob the caller owns or an owned collectible image. Team emblem sends { kind: team, teamId }; teamId must exist and have an https logo (its own, else its league's), and the stored and returned source carries the team's name and that logo as uri (any name/uri sent is ignored). art is null, an owned https image URL, or a cover token: mock-cover: or a catalog id (letters, digits, _ . -; at most 160 characters).", "properties": { "v": { "type": "integer", "const": 1 }, "material": { "type": "string", "enum": [ "leather", "pebble", "linen", "carbon", "metal", "printed" ] }, "colour": { "type": "string", "enum": [ "navy", "royal", "oxblood", "forest", "sand", "ivory", "black", "graphite" ] }, "foil": { "type": "string", "enum": [ "gold", "silver", "rose", "holo", "deboss" ] }, "hardware": { "type": "string", "enum": [ "gold", "chrome", "gunmetal", "none" ] }, "strap": { "type": "boolean" }, "label": { "type": "boolean" }, "nameStamp": { "type": "string", "enum": [ "front", "spine", "both", "none" ] }, "emblem": { "type": [ "object", "null" ], "properties": { "shape": { "type": "string", "enum": [ "circle", "square", "rect" ] }, "source": { "type": "object", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "team" }, "teamId": { "type": "string" }, "name": { "type": "string", "description": "Response only: the team's name (ignored on input)." }, "uri": { "type": "string", "description": "Response only: the team's logo, else its league's (ignored on input)." } }, "required": [ "kind", "teamId" ] }, { "type": "object", "properties": { "kind": { "const": "photo" }, "uri": { "type": "string" } }, "required": [ "kind", "uri" ] } ] } }, "required": [ "shape", "source" ] }, "art": { "type": [ "string", "null" ], "description": "Printed art: an owned https image URL, or a cover token (mock-cover: or a catalog id)." } }, "required": [ "v", "material", "colour", "foil", "hardware", "strap", "label", "nameStamp", "emblem" ] } } } } } }, "responses": { "200": { "description": "{ binder }" }, "400": { "description": "VALIDATION_ERROR" } } }, "delete": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "Delete binder", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success: true }" } } } }, "/api/binders/{id}/card-order": { "put": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "Persist binder card display order", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "order" ], "properties": { "order": { "type": "array", "items": { "type": "string" }, "description": "BinderCard ids" } } } } } }, "responses": { "200": { "description": "{ success: true }" }, "400": { "description": "VALIDATION_ERROR" } } } }, "/api/binders/{id}/cards": { "put": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "Assign or transfer cards into a binder", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "idempotencyKey", "items" ], "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 }, "items": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "collectibleId", "amount" ], "properties": { "collectibleId": { "type": "string" }, "amount": { "type": "number" }, "fromBinderId": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "{ results: [{ collectibleId, ok, error? }] }" }, "409": { "description": "Conflict: IDEMPOTENCY_KEY_CONFLICT when the key was used for a different binder; IDEMPOTENCY_IN_PROGRESS when assignment is already in progress for this key." } } } }, "/api/binders/{id}/transfer-card": { "post": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "Transfer a card to another binder", "description": "Path id is the source binder. Binder PIN ≠ wallet PIN.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collectibleId", "toBinderId" ], "properties": { "collectibleId": { "type": "string" }, "toBinderId": { "type": "string" }, "amount": { "type": "number" } } } } } }, "responses": { "200": { "description": "{ success: true }" }, "400": { "description": "VALIDATION_ERROR" } } } }, "/api/binders/{id}/verify-pin": { "post": { "tags": [ "Binders", "Collectibles and packs" ], "summary": "Verify binder PIN", "description": "Returns { granted }. Binder PIN is not the wallet PIN.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pin" ], "properties": { "pin": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ granted: boolean }" }, "400": { "description": "VALIDATION_ERROR" } } } }, "/api/checkout/crypto": { "post": { "tags": [ "Checkout", "Commerce and purchases" ], "summary": "Create crypto checkout", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "string" }, "itemType": { "type": "string" }, "quantity": { "type": "integer" }, "chain": { "type": "string" }, "useNativeToken": { "type": "boolean" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ paymentId, recipientAddress, amount, ... }" }, "403": { "description": "WALLET_NOT_LINKED — wallet no longer linked to the fan; FORBIDDEN is still returned by older deploys." } } } }, "/api/checkout/crypto/verify": { "post": { "tags": [ "Checkout", "Commerce and purchases" ], "summary": "Verify crypto payment", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string" }, "transactionHash": { "type": "string" }, "chain": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ verified, status }" } } } }, "/api/checkout/dsports-cash": { "post": { "tags": [ "Checkout", "Commerce and purchases" ], "summary": "Checkout with D-Sports Cash", "description": "Charges the caller's D-Sports Cash balance and, in the same transaction, removes or reduces the purchased ShopCartItem lines. Each purchased unit is applied once: the Product id the client sent is cleared first, then another mirror of that pack. A single-item buy of an item that is also in the cart reduces that line. A rejected charge leaves the cart. Optional Idempotency-Key header or idempotencyKey body field (max 128). The same key and the same cart replay the first 200 and do not charge again. The same key with a different cart is 409 IDEMPOTENCY_KEY_CONFLICT. Omitting the key charges every request. Keys are not expired. An omitted pack wallet resolves to the fan's primary wallet (oldest custodial, else oldest of any type), or null when the fan has no wallet (#938).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "string" }, "itemType": { "type": "string" }, "quantity": { "type": "integer" }, "cartItems": { "type": "array" }, "idempotencyKey": { "type": "string", "maxLength": 128, "description": "Optional. Ignored when the Idempotency-Key header is set to the same value. A mismatch with the header is 400." } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { paymentId, remainingBalance, chargedAmount, currency } }. A replay returns the first paymentId, remainingBalance, and chargedAmount stored at charge time, not a live wallet read; legacy receipts omit chargedAmount." }, "400": { "description": "PRODUCT_UNAVAILABLE for a missing or unavailable product/pack; otherwise VALIDATION_ERROR or INSUFFICIENT_BALANCE. The cart is unchanged." }, "403": { "description": "WALLET_NOT_LINKED — buying wallet no longer linked to the fan (switch wallets and retry). Message stays 'Wallet not linked to this fan'; status stays 403. Native keeps the old code+message match as fallback." }, "409": { "description": "IDEMPOTENCY_KEY_CONFLICT — this key was already used for a different cart." }, "429": { "description": "FREE_PACK_DAILY_LIMIT_REACHED. The cart is unchanged." } } } }, "/api/config/sports": { "get": { "tags": [ "Config", "Teams" ], "summary": "List sports and leagues catalog", "description": "Public catalog derived from League.sport. { sports: [{ id, label, order, leagues: [{ id, label, order }] }] }. Auth optional.", "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/content/{slug}": { "get": { "tags": [ "Config" ], "operationId": "getPublishedContent", "summary": "Get published approved copy by slug", "description": "Published, Legal-approved client copy (#998), unauthenticated. `data` is `{ slug, version, updatedAt, blocks: { title, body, bullets } }`. `version` is a publish counter for the served snapshot, not comparable across locale deletion/recreation or English fallback. `updatedAt` is the last publish instant; use locale-keyed ETags for revalidation. Responds 304 with no body when `If-None-Match` matches the served `ETag` (weak, over the whole envelope). `Cache-Control: public, s-maxage=300, stale-while-revalidate=3600` — copy changes rarely. 404 for an unknown or never-published slug (a draft is never served); 400 for a slug that is not lowercase words separated by hyphens. First slug: `rep-explainer` — seeded as an unpublished draft, so it 404s until Legal publishes real wording; clients keep their bundled copy in that window. On a 304 the cached server copy is still current and should be kept; the bundle is only for when no usable cached copy exists. Authored locales (#1044): Accept-Language resolves en/fr-CH/it-IT. Only reviewed published JSON snapshots are served, otherwise English; never machine translation. Every 200/304 sets Vary: Accept-Language and actual Content-Language (en on fallback/empty; en, on mixed changelog feeds). English bytes/ETags stay legacy; non-English ETags include negotiated locale even on fallback. Cache by negotiated locale. ApprovedCopy version is locale-owned, changelog app version remains base-owned; variant updatedAt is its publish time. Locale deletion/recreation resets its publish counter. Missing new locale table during rollout falls back; unrelated failures return 500.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "Content slug, e.g. `rep-explainer`." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Shared language negotiation; missing/unsupported headers resolve to en." }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Validator for this negotiated locale. Wildcard matches any current representation." } ], "security": [], "responses": { "200": { "description": "{ success, data: { slug, version, updatedAt, blocks } }", "headers": { "Content-Language": { "schema": { "type": "string" }, "description": "Actual served languages: en, fr-CH, it-IT, or mixed en, fr-CH / en, it-IT" }, "Vary": { "schema": { "type": "string" }, "description": "Accept-Language" }, "ETag": { "schema": { "type": "string" }, "description": "Locale-aware weak validator; English legacy hash unchanged" }, "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300, stale-while-revalidate=3600" } } }, "304": { "description": "Not modified — `If-None-Match` matched the current `ETag`. No body.", "headers": { "Content-Language": { "schema": { "type": "string" }, "description": "Actual served languages: en, fr-CH, it-IT, or mixed en, fr-CH / en, it-IT" }, "Vary": { "schema": { "type": "string" }, "description": "Accept-Language" }, "ETag": { "schema": { "type": "string" }, "description": "Locale-aware weak validator; English legacy hash unchanged" }, "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300, stale-while-revalidate=3600" } } }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "404": { "description": "{ success: false, error, code: \"NOT_FOUND\" }" } } } }, "/api/crypto-prices": { "get": { "tags": [ "Misc", "Wallet and web3" ], "summary": "Crypto prices", "security": [], "responses": { "200": { "description": "Crypto prices" } } } }, "/api/dashboard": { "get": { "tags": [ "Dashboard" ], "summary": "Dashboard (public)", "security": [], "responses": { "200": { "description": "{ message }" } } }, "post": { "tags": [ "Dashboard" ], "summary": "Dashboard (auth check)", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ userId, isAuthenticated }" } } } }, "/api/dashboard/balance": { "get": { "tags": [ "Dashboard" ], "summary": "Dashboard balance", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Balance" } } } }, "/api/dashboard/quests": { "get": { "tags": [ "Dashboard" ], "summary": "Dashboard quests", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Quests" } } } }, "/api/dashboard/stats": { "get": { "tags": [ "Dashboard" ], "summary": "Dashboard stats", "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Dashboard stats" } } } }, "/api/discovery/fans": { "get": { "tags": [ "Discovery" ], "summary": "Discover fans", "description": "Authenticated suggested fans (excludes already-following). Query: cursor, limit.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/discovery/teams": { "get": { "tags": [ "Discovery" ], "summary": "Discover teams", "description": "Public suggested / official teams. Query: limit.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/dsports-cash": { "get": { "tags": [ "D-Sports Cash", "Commerce and purchases" ], "summary": "Get D-Sports Cash balance", "description": "Query: userId (admin impersonation).", "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ dsportsCash }" } } } }, "/api/events/realtime": { "get": { "tags": [ "Events" ], "summary": "Discover Game Center Realtime Broadcast", "description": "Public. Returns Supabase URL, anon key (also as `token`), and the private channel template `events:{gameId}`. Socket auth is Supabase-native: `?apikey=` on the socket URL (native and web) or the `x-api-key` header (native); a user JWT goes in `phx_join.access_token` (prefer `@supabase/supabase-js`, which sends both correctly). Envelope: every `game`/`plays`/`stats` broadcast carries `seq` (= publish-time ms, ordering-only per game+event); stale/duplicate `seq <= lastSeq` is ignored. Broadcasts are full snapshots/replacements, so resync via REST only on (re)join, `phx_error`, or unexpected `phx_close` — never on a jump. Live types score/clock/period/goal/penalty/status are observed by diffing `game` snapshots + `plays` kinds. Resync: snapshot `GET /api/events/{gameId}`, replay `GET /api/events/{gameId}/plays?afterId={lastPlayId}`. Polling/ETag stays the fallback. Only the API service role may broadcast.", "security": [], "responses": { "200": { "description": "{ success, data: { enabled, url, anonKey, token, channelPrefix, channelForGame, private, events, liveTypes, auth, resync, note } }" } } } }, "/api/events/schedule": { "get": { "tags": [ "Events" ], "summary": "List game schedule", "description": "Public schedule. Repeatable teamId query param. Used by the locker-room hero strip and the HQ Schedule tab. One teamId with no limits returns that team's full depth (every live/forthcoming game plus every final/past row, up to 150 rows). Multi-team requests default to two separate per-team budgets: an upcoming bucket (live/delayed first, then the next 5 forthcoming kickoffs) and a past bucket (5 slots filled by the most recent completed rows first; a live row older than 6h uses only a leftover slot), merged and deduped by row id under an overall ceiling that scales with team count and the budgets. Games that already happened never take an upcoming slot; rows stuck on a pre-game status past 6h with no live data are served as past games with status and scores untouched. Cancelled fixtures are dropped before selection so they cannot take a slot. Postponed fixtures stay. Game rows explicitly include endedAt: ISO 8601 UTC string | null (#1116). It records the first accepted sync observation of final, not an estimated or vendor-certified finish time. Non-final rows and unknown end times return null. Eligible first observations require a known kickoff not in the future and no more than 12 hours old; existing finals are not backfilled. The stored timestamp is immutable across later and concurrent syncs. A delayed observation can extend the window beyond actual finish. Selected vendor rows are overlaid from stored timestamps in one bounded lookup. A failed lookup preserves schedule progress and known fallback timestamps; unknown timestamps stay null. The first final response can remain null while background persistence completes, plus s-maxage=60 cache latency.", "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Repeatable. Fan out per followed/joined team." }, { "name": "upcomingLimit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Optional per-team upcoming-bucket budget. A single teamId with neither limit set returns full depth (up to 150 rows) instead; when only one limit is set, the other defaults to 5. Out-of-range or non-integer values are a 400." }, { "name": "pastLimit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Optional per-team past-bucket budget. A single teamId with neither limit set returns full depth (up to 150 rows) instead; when only one limit is set, the other defaults to 5. Out-of-range or non-integer values are a 400." }, { "name": "season", "in": "query", "required": false, "description": "Season start year (2026 = 2026-27). Defaults to the current hockey season; scopes the vendor season reads.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/events/live": { "get": { "tags": [ "Events" ], "summary": "Live game counts per league", "description": "Public cheap live-per-league read for the HQ sport screen. Source is persisted GameEvent rows (status live), never the vendor fan-out; demo fixtures excluded. A row counts only when startTime is within the last 6 hours (LIVE_STALE_AFTER_MS); older kickoffs and a null startTime are excluded so a finished or vendor-stuck game cannot light the LIVE pill (#909). League resolves via homeTeam.leagueId ?? awayTeam.leagueId; leagueId values are League.id (cuid) matching GET /api/leagues. Default shape { leagues: [{ leagueId, live }], games: null }; ?include=games adds per-game rows { id, leagueId, homeTeamId, awayTeamId } with ids only (no scores/clocks). Cache: CDN s-maxage=30, stale-while-revalidate=60, stale-if-error=300. (#898)", "parameters": [ { "name": "sport", "in": "query", "required": false, "schema": { "type": "string", "default": "hockey", "enum": [ "basketball", "soccer", "football", "hockey", "baseball" ] }, "description": "Sport filter for the persisted rows. Unknown sport is a 400." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "games" ] }, "description": "include=games adds per-game rows; any other value is a 400." } ], "security": [], "responses": { "200": { "description": "{ success, data: { leagues, games } }" }, "400": { "description": "Invalid sport or include." }, "502": { "description": "Live read failed (UPSTREAM_ERROR, retriable)." } } } }, "/api/events/today": { "get": { "tags": [ "Events" ], "summary": "Today's game counts across all leagues", "description": "Public hero-card summary for the fan's local day (#1128, engage-native#1320). `tz` is a required IANA zone; the day is local midnight to the next local midnight in it (23 or 25 hours on DST days). Source is persisted GameEvent rows across every sport and league; demo fixtures excluded; a game counts only when its league resolves via homeTeam.leagueId ?? awayTeam.leagueId, as on GET /api/events/live. Buckets: `live` uses the /api/events/live rule exactly (status live and startTime within the last 6 hours), including a game that kicked off before local midnight and is still live; `later` is upcoming or delayed; `final` is final, plus a live row whose kickoff is older than 6 hours (the schedule files those under past games). Postponed, cancelled and suspended games are left out of every count. `total` = live + later + final. `nextStartAt` is the soonest startTime among `later` games (ISO 8601 UTC) or null. Cache: same CDN policy as /api/events/live (s-maxage=30, stale-while-revalidate=60, stale-if-error=300), keyed by URL so each zone caches separately.", "parameters": [ { "name": "tz", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64, "example": "America/Toronto" }, "description": "IANA time zone that defines \"today\". Missing or unknown is a 400." } ], "security": [], "responses": { "200": { "description": "{ success: true, data: { total, live, later, final, nextStartAt } }", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "total", "live", "later", "final", "nextStartAt" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "live": { "type": "integer", "minimum": 0 }, "later": { "type": "integer", "minimum": 0 }, "final": { "type": "integer", "minimum": 0 }, "nextStartAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "400": { "description": "Missing or unknown IANA zone (VALIDATION_ERROR)." }, "502": { "description": "Read failed (UPSTREAM_ERROR, retriable)." } } } }, "/api/events/{gameId}": { "get": { "tags": [ "Events" ], "summary": "Get game event", "description": "Public Game Center detail for one event. Includes a `realtime` pointer `{ channel, events }` (no token). Discover URL/anon key via GET /api/events/realtime. Broadcasts carry ordering-only `seq`; resync here on (re)join, `phx_error`, or unexpected `phx_close`. Poll/ETag stays the fallback. Game rows explicitly include endedAt: ISO 8601 UTC string | null (#1116). It records the first accepted sync observation of final, not an estimated or vendor-certified finish time. Non-final rows and unknown end times return null. Eligible first observations require a known kickoff not in the future and no more than 12 hours old; existing finals are not backfilled. The stored timestamp is immutable across later and concurrent syncs. A delayed observation can extend the window beyond actual finish.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/events/{gameId}/chat": { "get": { "tags": [ "Events" ], "summary": "List game chat", "description": "Game-thread messages, hasMore, and onlineCount. Each message includes authorId (User.id or null) so mute/block can persist server-side, and side (home/away/null) server-stamped per fixture from the two clubs' Club Rep top-100 leaderboards — null renders as Spectator; dual-membership ties break on the author's favorite team(s).", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "Events" ], "summary": "Send game chat message", "description": "Authenticated message in the game thread. The created message includes authorId and the server-stamped side (home/away/null) like GET.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/events/{gameId}/chat/mute": { "post": { "tags": [ "Events" ], "summary": "Mute game chat", "description": "Authenticated mute of a userId or the whole thread (thread:true). The two options are mutually exclusive.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "delete": { "tags": [ "Events" ], "summary": "Unmute game chat", "description": "Authenticated unmute. Same body rules as POST.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/events/{gameId}/lineup": { "get": { "tags": [ "Events" ], "summary": "Get game lineup", "description": "Public home/away starters and bench. Slots include playerKey, playerId (stable roster id when linked; null for call-ups/opponent squads — keep the normalised-name fallback), position, jersey, unit, isStarter.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/events/{gameId}/live-activity": { "post": { "tags": [ "Events" ], "summary": "Register a Team HQ Live Activity", "description": "Authenticated. Registers routing for an iOS Lock Screen / Dynamic Island match card, keyed per user + fixture + club. Requires UserSettings.liveScoreUpdates consent (403 FORBIDDEN otherwise). `activityId` is minted server-side (`hq:{gameId}:{teamId}:{userId}`) and returned; the client calls OneSignal.LiveActivities.enter(activityId, pushToken). `pushToken` is an optional hex ActivityKit token stored for that client call. A later POST that omits it does not clear the stored token. The server never sends the token to Apple or OneSignal — Live Activity updates and ends go through OneSignal's live_activities API. Android (#697) writes a `platform:\"android\"` opt-in row on the same user+fixture+club key (no `pushToken`) and returns `{ registered: true, platform: \"android\", activityId: , expiresAt: null }` after the same game/team/consent checks — the row opts the fan into Android Live Update pushes for that fixture+club (they ride ordinary push subscriptions, so no ActivityKit token is stored). A register on an already-live fixture also sends that fan a catch-up push with the current score.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Registered (iOS: expiresAt set; Android: platform android + minted activityId, null expiresAt)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "oneOf": [ { "type": "object", "description": "iOS registration", "properties": { "registered": { "type": "boolean", "enum": [ true ] }, "activityId": { "type": "string", "example": "hq:hockey-9001:bos:user_1", "description": "Per-user (#558): hq:{gameEventId}:{teamId}:{userId}. Minted server-side; pass it verbatim to OneSignal.LiveActivities.enter." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "registered", "activityId", "expiresAt" ] }, { "type": "object", "description": "Android opt-in registered (#697): platform:\"android\" row written — the fan joins the fixture+club Android Live Update audience", "properties": { "registered": { "type": "boolean", "enum": [ true ] }, "platform": { "type": "string", "enum": [ "android" ] }, "activityId": { "type": "string", "description": "Minted per-user id hq:{gameEventId}:{teamId}:{userId}, same scheme as iOS." }, "expiresAt": { "type": "null" } }, "required": [ "registered", "platform", "activityId", "expiresAt" ] } ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "VALIDATION_ERROR — teamId missing, or not one of the fixture's two clubs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error", "code" ] } } } }, "401": { "description": "UNAUTHORIZED — no valid Clerk session", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error", "code" ] } } } }, "403": { "description": "FORBIDDEN — UserSettings.liveScoreUpdates is not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error", "code" ] } } } }, "404": { "description": "NOT_FOUND — no such fixture", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error", "code" ] } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error", "code" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId" ], "properties": { "teamId": { "type": "string", "description": "Must be the fixture's homeTeamId or awayTeamId. Decides the card theme and the minted activityId." }, "platform": { "type": "string", "default": "ios", "enum": [ "ios", "android" ], "description": "ios writes a LiveActivityRegistration row and returns activityId/expiresAt. android writes a platform:\"android\" opt-in row (no pushToken) and returns platform android + minted activityId + null expiresAt — opting the fan into Android Live Update pushes for that fixture+club. Any other value is 400 VALIDATION_ERROR." }, "pushToken": { "type": [ "string", "null" ], "description": "Optional hex ActivityKit token stored for the client call OneSignal.LiveActivities.enter(activityId, pushToken). Omitted on a later POST leaves the stored token in place. The server never sends it to Apple or OneSignal." } } } } } } }, "patch": { "tags": [ "Events" ], "summary": "Rotate a Live Activity push token", "description": "Authenticated. Replaces the stored hex ActivityKit push token on an existing registration. The token is for the client call OneSignal.LiveActivities.enter(activityId, pushToken). The server does not send it to Apple or OneSignal. 404 when no row matches activityId on this fixture. 403 when the row belongs to another user.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "activityId", "pushToken" ], "properties": { "activityId": { "type": "string", "description": "Server-minted hq:{gameId}:{teamId}:{userId}." }, "pushToken": { "type": "string", "description": "Replacement hex ActivityKit token." } } } } } }, "responses": { "200": { "description": "Token rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "activityId": { "type": "string" } }, "required": [ "activityId" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "VALIDATION_ERROR — activityId or pushToken missing, or pushToken is not hex" }, "401": { "description": "UNAUTHORIZED — no valid Clerk session" }, "403": { "description": "FORBIDDEN — registration belongs to another user" }, "404": { "description": "NOT_FOUND — no registration for this activityId on this fixture" } } }, "delete": { "tags": [ "Events" ], "summary": "End a Team HQ Live Activity registration", "description": "Authenticated and idempotent. Matches by activityId or pushToken (either optional; omitting both ends every active registration the caller holds for this fixture). Always returns { registered: false }.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Idempotent — always reports registered: false", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "registered": { "type": "boolean", "enum": [ false ] } }, "required": [ "registered" ] } }, "required": [ "success", "data" ] } } } }, "401": { "description": "UNAUTHORIZED — no valid Clerk session", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error", "code" ] } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error", "code" ] } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Both fields optional. Omitting both ends every active registration the caller holds for this fixture.", "properties": { "activityId": { "type": "string" }, "pushToken": { "type": "string" } } } } } } } }, "/api/events/{gameId}/plays": { "get": { "tags": [ "Events" ], "summary": "Get play-by-play", "description": "Public play events for the game.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/events/{gameId}/presence": { "get": { "tags": [ "Events" ], "summary": "Get game presence count", "description": "Public online viewer count.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "Events" ], "summary": "Heartbeat game presence", "description": "Authenticated presence heartbeat. Returns { ok, count }.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/events/{gameId}/ratings": { "get": { "tags": [ "Events" ], "summary": "Get game ratings", "description": "Lineup plus community averages and the viewer's ratings. data.lineupAvailable reports whether any lineup slots exist — vendor-synced hockey finals seed their lineup on read (#672), so a final with an upstream roster returns slots here instead of an empty lineup.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "Events" ], "summary": "Submit game ratings", "description": "Authenticated ratings submit. Server may award Club Rep. Do not call /v1/engage/rep/earn for this. Requires at least one lineup slot — finals whose vendor roster could not be seeded return 409 LINEUP_UNAVAILABLE.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { saved, allStartersRated, repEarned } }" }, "400": { "description": "VALIDATION_ERROR — ratings array is required, or a playerKey/score is invalid" }, "401": { "description": "Authentication required" }, "404": { "description": "NOT_FOUND — unknown game" }, "409": { "description": "CONFLICT — ratings window is closed; LINEUP_UNAVAILABLE — no lineup rows to rate" } } } }, "/api/events/{gameId}/stats": { "get": { "tags": [ "Events" ], "summary": "Get game box score", "description": "Public team stat rows for the event.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/feed/preferences": { "get": { "tags": [ "Feed" ], "summary": "List negative feed preferences", "description": "Authenticated. Returns the viewer's stored preferences, oldest first: { success, data: { preferences: [{ id, subjectType, subjectId, kind, createdAt }] } }. subjectType is author | team | topic | itemType | creative. kind is less | never. Organic and promoted (creative) rows share this one array; they are stored on separate surfaces and are not removed by the analyticsPersonalization opt-out purge (#720). Account deletion removes them.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { preferences } }" }, "401": { "description": "Unauthenticated" } } }, "post": { "tags": [ "Feed" ], "summary": "Save a negative feed preference", "description": "Authenticated. Body { subjectType, subjectId, kind }. 201 { success, data: { id, subjectType, subjectId, kind, createdAt } }. Idempotent on (subjectType, subjectId): one row per pair, and a repeat with a different kind updates that row (still 201, returned kind matches the request). subjectId is trimmed, 1–200 characters, no NUL; unknown keys are rejected (400 VALIDATION_ERROR). Cap is 200 rows per user across both surfaces; a new pair at the cap is 409 PREFERENCE_CAP and the oldest row is kept. A replay of an existing pair does not count toward the cap. creative is stored on the promoted surface; every other subjectType is organic. Writes (this POST and DELETE) share a 30/minute/user limit (429 RATE_LIMITED). A missing User row is 404 NOT_FOUND.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subjectType", "subjectId", "kind" ], "properties": { "subjectType": { "type": "string", "enum": [ "author", "team", "topic", "itemType", "creative" ] }, "subjectId": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "enum": [ "less", "never" ] } } } } } }, "responses": { "201": { "description": "{ success, data: FeedPreference } including idempotent replay; kind matches the request" }, "400": { "description": "Invalid body (VALIDATION_ERROR)" }, "401": { "description": "Unauthenticated" }, "404": { "description": "User row missing (NOT_FOUND)" }, "409": { "description": "Per-user cap of 200 reached (PREFERENCE_CAP)" }, "429": { "description": "Write rate limit exceeded (RATE_LIMITED)" } } } }, "/api/feed/preferences/{id}": { "delete": { "tags": [ "Feed" ], "summary": "Undo a negative feed preference", "description": "Authenticated. Deletes one preference owned by the caller. Another user's id and an unknown id are both 404 NOT_FOUND (not 403) so the response does not confirm the row exists. Success is 204 with an empty body (native #648). The current native createApiClient treats a body-less 2xx as INVALID_RESPONSE_ENVELOPE, so the live flag must not flip until remove() treats an empty 204 as success. Shares the POST write rate limit (30/minute/user, 429 RATE_LIMITED).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Preference id returned by GET or POST." } ], "responses": { "204": { "description": "Deleted. Empty body." }, "401": { "description": "Unauthenticated" }, "404": { "description": "Unknown id or another user's id (NOT_FOUND)" }, "429": { "description": "Write rate limit exceeded (RATE_LIMITED)" } } } }, "/api/feed/signals": { "post": { "tags": [ "Feed" ], "summary": "Ingest behavioural feed signals", "description": "Authenticated. When UserSettings.analyticsPersonalization is false (#614), the payload is dropped at this endpoint and never persisted. Opted-in bodies are validated (zod) and stored as FeedSignal rows (#685): at most 50 events per request plus a 64KB body ceiling enforced before JSON parsing; unknown kind/filter rejected per event; dwellMs must be a finite positive number (booleans/numeric strings rejected), minimum normalized 1, clamped to 60s; opted-in writes are capped at 30 batches/min/user (429 RATE_LIMITED); client `at` clamped into the previous 24 hours ending at createdAt (future pinned to now). `accepted` counts the rows that survived validation (0 on the opt-out path). Rows older than FEED_SIGNAL_RETENTION_DAYS (default 90) are hard-deleted by the daily /api/cron/feed-signal-retention cron.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { ingested: boolean, accepted: number } }" }, "401": { "description": "Unauthenticated" }, "413": { "description": "Body exceeds the 64KB ingest ceiling (PAYLOAD_TOO_LARGE)" }, "429": { "description": "Per-user batch rate limit exceeded (RATE_LIMITED)" } } } }, "/api/feedback/bug-report": { "post": { "tags": [ "Misc", "Moderation and reporting" ], "summary": "Submit bug report", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [], "responses": { "200": { "description": "{ success }" } } } }, "/api/feedback/native-crash": { "post": { "tags": [ "Misc", "Moderation and reporting" ], "summary": "Submit native crash report", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [], "responses": { "200": { "description": "{ success }" } } } }, "/api/games/catalog": { "get": { "tags": [ "Games" ], "summary": "Public team mini-game catalog", "parameters": [ { "name": "teamId", "in": "query", "schema": { "type": "string" } }, { "name": "teamSlug", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ daily, weekly } PublicCatalogGame[]" }, "400": { "description": "teamId or teamSlug required" }, "404": { "description": "Team not found" } } } }, "/api/games/daily-spin/config": { "get": { "tags": [ "Games" ], "summary": "Public daily-spin wheel layout", "description": "Clients animate from this. Outcomes come from POST /api/games/daily-spin/spin.", "security": [], "responses": { "200": { "description": "{ segments, limits }" }, "503": { "description": "SPIN_NOT_CONFIGURED" } } } }, "/api/games/daily-spin/spin": { "post": { "tags": [ "Games" ], "summary": "Server-authoritative daily spin", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "type": "string" }, "leaderboardId": { "type": "integer" } } } } } }, "responses": { "200": { "description": "{ segment, awards }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/games/daily-spin/state": { "get": { "tags": [ "Games" ], "summary": "Authenticated daily-spin progress", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ spins remaining, weekly collection }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/games/guess-player/players": { "get": { "tags": [ "Games" ], "summary": "Search Guess the Player roster", "description": "Autocomplete over seeded Player rows. Empty q returns an empty players list.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "{ query, players[] }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/games/guess-player/session/guess": { "post": { "tags": [ "Games" ], "summary": "Submit a Guess the Player guess", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "guess" ], "properties": { "sessionId": { "type": "string" }, "guess": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ correct, remaining }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/games/guess-player/session/invalidate": { "post": { "tags": [ "Games" ], "summary": "Invalidate a Guess the Player session", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "reason" ], "properties": { "sessionId": { "type": "string" }, "reason": { "type": "string", "maxLength": 80 } } } } } }, "responses": { "200": { "description": "{ found, status, remainingGuesses }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/games/guess-player/session/start": { "post": { "tags": [ "Games" ], "summary": "Start a Guess the Player session", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ session }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/games/live/active": { "get": { "tags": [ "Games" ], "summary": "Active live game for a team", "security": [], "parameters": [ { "name": "teamId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "session or null" }, "400": { "description": "teamId required" } } } }, "/api/games/live/by-code/{code}": { "get": { "tags": [ "Games" ], "summary": "Look up a live game by join code", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "session" }, "400": { "description": "code required" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/games/live/join": { "post": { "tags": [ "Games" ], "summary": "Join a live game by code", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 4, "maxLength": 12 }, "via": { "type": "string", "enum": [ "scan", "code" ], "default": "code", "description": "Use scan only when the game was joined from a QR scan." } } } } } }, "responses": { "200": { "description": "{ player, session }; scan joins may return gameServices: { firstEver? }. The block is omitted when the best-effort milestone claim fails." }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/games/live/start": { "post": { "tags": [ "Games" ], "summary": "Start a live game (team manager)", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId", "gameKey", "title", "prizeTiers" ], "properties": { "teamId": { "type": "string" }, "gameKey": { "type": "string" }, "title": { "type": "string" }, "prizeTiers": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "201": { "description": "session" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "409": { "description": "CONFLICT" } } } }, "/api/games/live/{sessionId}/end": { "post": { "tags": [ "Games" ], "summary": "End a live game (team manager)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId" ], "properties": { "teamId": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ session }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" } } } }, "/api/games/live/{sessionId}/leaderboard": { "get": { "tags": [ "Games" ], "summary": "Live game leaderboard", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ entries[] }" }, "400": { "description": "sessionId required" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/games/live/{sessionId}/score": { "post": { "tags": [ "Games" ], "summary": "Submit a live-game score delta", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "delta" ], "properties": { "delta": { "type": "integer", "minimum": 1, "maximum": 1000 } } } } } }, "responses": { "200": { "description": "{ score }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/games/pick-em/players": { "get": { "tags": [ "Games" ], "summary": "Legacy Pick'em player list", "description": "Leftover roster helper. Engine Pick'em does not use this path.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ players[] }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/image-proxy": { "get": { "tags": [ "Misc", "Platform and infrastructure" ], "summary": "Image proxy", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Proxied image" } } } }, "/api/leaderboard": { "get": { "tags": [ "Leaderboard", "Gamification" ], "summary": "Get leaderboard", "description": "Returns leaderboard entries. Query: leaderboardId (number) or teamId (string); omit for global. The global / D-Sports board ranks each fan's total Fan Rep (same as profile fanRep: lifetime PointsHistory + typed Rep ledger), not a separate seasonal pool. Club team boards remain seasonal.", "parameters": [ { "name": "leaderboardId", "in": "query", "schema": { "type": "integer" } }, { "name": "teamId", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ leaderboard, leaderboardEntries, currentUserId, season }" }, "401": { "description": "Authentication required" }, "404": { "description": "Leaderboard or user not found" } } } }, "/api/leaderboard/search": { "get": { "tags": [ "Leaderboard" ], "summary": "Search leaderboard players", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "leaderboardId", "in": "query", "schema": { "type": "integer" } } ], "security": [], "responses": { "200": { "description": "{ players, total, page, limit, totalPages }" } } } }, "/api/leaderboard/seasons": { "get": { "tags": [ "Leaderboard" ], "summary": "List seasons", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ seasons, current }" } } } }, "/api/leaderboard/stats": { "get": { "tags": [ "Leaderboard" ], "summary": "Leaderboard stats", "description": "Total users, total points, last winner.", "security": [], "responses": { "200": { "description": "{ totalUsers, totalPoints, lastWinner }" } } } }, "/api/leaderboard/stream": { "get": { "tags": [ "Leaderboard" ], "summary": "Leaderboard SSE stream", "description": "Server-sent events stream. Query: leaderboardId.", "parameters": [ { "name": "leaderboardId", "in": "query", "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SSE stream" } } } }, "/api/leaderboard/winners": { "get": { "tags": [ "Leaderboard" ], "summary": "Get winners", "parameters": [ { "name": "seasonId", "in": "query", "schema": { "type": "string" } }, { "name": "leaderboardId", "in": "query", "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ winners }" } } } }, "/api/leagues": { "get": { "tags": [ "Leagues", "Teams" ], "summary": "List leagues", "description": "League metadata, colors, and logo branding used by clients.", "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/leagues/{leagueId}/standings": { "get": { "tags": [ "Leagues" ], "summary": "Get league standings", "description": "HQ Standings tab. Public. rows is one team each (division, else conference, else league). Empty duplicate groupings are dropped. tables lists every remaining scope. Prefer unique vendor rank inside a table; otherwise points, wins, then goal difference. tiebreakRules names that fallback only. 404 if the league id/slug is missing. Empty rows when the league cannot be scored honestly.", "parameters": [ { "name": "leagueId", "in": "path", "required": true, "description": "Prisma League.id or slug (not the vendor NHL id).", "schema": { "type": "string" } }, { "name": "season", "in": "query", "required": false, "description": "Season start year (2026 = 2026-27). Defaults to the current hockey season.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "stage", "in": "query", "required": false, "description": "Vendor standings-stage slug from GET /api/leagues/{leagueId}/stages. Omitted serves the whole season.", "schema": { "type": "string", "maxLength": 64 } } ], "security": [], "responses": { "200": { "description": "{ success, data: { rows, tiebreakRules, tables } }" }, "400": { "description": "Invalid season or stage" }, "404": { "description": "League not found" } } } }, "/api/leagues/{leagueId}/seasons": { "get": { "tags": [ "Leagues" ], "summary": "List league seasons", "description": "HQ season picker (#848). Public. { seasons: [{ year, label, current }] }, most recent first. The current season always lists so ?season= targets on standings, schedule, roster and statistics agree with the picker.", "parameters": [ { "name": "leagueId", "in": "path", "required": true, "description": "Prisma League.id or slug (not the vendor NHL id).", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { seasons } }" }, "404": { "description": "League not found" } } } }, "/api/leagues/{leagueId}/stages": { "get": { "tags": [ "Leagues" ], "summary": "List league standings stages", "description": "HQ standings-stage picker (#848). Public. { stages: [{ id, name, current }] } in vendor order; empty when the competition has no split. Feed ?stage= on GET standings from an entry id.", "parameters": [ { "name": "leagueId", "in": "path", "required": true, "description": "Prisma League.id or slug (not the vendor NHL id).", "schema": { "type": "string" } }, { "name": "season", "in": "query", "required": false, "description": "Season start year (2026 = 2026-27). Defaults to the current hockey season.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } } ], "security": [], "responses": { "200": { "description": "{ success, data: { stages } }" }, "400": { "description": "Invalid season" }, "404": { "description": "League not found" } } } }, "/api/locker-room": { "get": { "tags": [ "Locker room" ], "summary": "Get locker room posts", "description": "Page mode (default): `page` + `hasMore`. Cursor mode (DSE-369): pass opaque `cursor` from a prior `nextCursor`; response includes `nextCursor` (`null` at end). Both modes return `nextCursor` (#689) — a page-1 request has no cursor to send, so page mode is where a client obtains its first one; the only exception is a viewer whose filter was remapped by #614, where a cursor would 400 on the next request and is withheld. Invalid cursor → 400 (decoded against the request filter before any #614 remap). Cursors are scope-keyed (#660): a cursor issued for one `teamId` / `phase` / `postType` / `authorTeamId` / `authorId` / `includeDemo=false` scope 400s when resumed under another scope — always restart from page 1 when the scope changes. Filters: trending|latest|following|foryou. `teamId` narrows to the per-team feed (about-tagged OR authored-as for that team); `authorTeamId` narrows to officially-as-team posts; both compose with `following` as AND. NULL-matches-any: rows with unset `channel` / `teamId` match any `phase` / `teamId` filter, so untagged posts stay in scoped feeds. When the viewer has UserSettings.analyticsPersonalization=false (#614), trending/foryou are served chronological (`latest` order) and a *valid* ranked cursor is dropped after that 400-check. Ranked filters (trending/foryou) additionally carry `rank` (absolute 0-based position, continuing across pages) and `reason` ({ code, label?, subjectId? }) per post, plus `rankVersion` on the envelope (#686) — chronological filters and opted-out viewers carry none of the three. `ads` is `[]` only when inventory is switched off; an opted-out viewer takes the contextual fill path (#687). Feed preferences (#722) are applied for the authenticated viewer on every filter, including when analyticsPersonalization is false: kind `never` excludes matching authors, teams (`teamId` or `authorTeamId`), topics (`channel`), and item types at candidate generation; kind `less` downweights matching posts to one quarter of their reaction count while scoring trending/foryou and does not remove them from chronological feeds. Promoted creatives are not filtered here. Team-news rail (#827): the first page of a team-scoped feed (`teamId` or `authorTeamId` set, no `cursor`, page 1, no `authorId` filter) also carries up to 5 published articles as `data.news` (same fields as GET /api/news items plus `itemType: \"news\"`). Never present on the global/all feed, later pages, or cursor resumes; omitted (not empty) when there is no news or the news read fails. Each post includes `mentions` (#953): `{ id, handle, name?, profileUrl? }[]`, empty when nobody is tagged. Users the viewer has blocked (either direction) and users with a null handle are omitted.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor from a previous nextCursor. When set, takes precedence over page. Invalid, or issued for a different filter/scope (teamId/phase/postType/authorTeamId/authorId/includeDemo) → 400.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "schema": { "type": "string", "enum": [ "trending", "latest", "following", "foryou" ] } }, { "name": "includeDemo", "in": "query", "schema": { "type": "boolean", "default": true } }, { "name": "authorId", "in": "query", "description": "When set, only return this author's personal posts. Posts they wrote in a team voice (authorTeamId set) are excluded; fetch those with authorTeamId. Combining authorId with authorTeamId returns no rows.", "schema": { "type": "string" } }, { "name": "authorTeamId", "in": "query", "description": "When set, only return posts authored officially by this team", "schema": { "type": "string" } }, { "name": "teamId", "in": "query", "description": "Per-team feed scope: posts about-tagged with this team, posts authored as this team, plus untagged (NULL teamId) posts per the NULL-matches-any rule. Composes with following as AND.", "schema": { "type": "string" } }, { "name": "phase", "in": "query", "description": "Game-phase scope (pre|live|post), matched against the post channel. Unset channel matches any phase per the NULL-matches-any rule. Unknown values are ignored.", "schema": { "type": "string", "enum": [ "pre", "live", "post" ] } }, { "name": "postType", "in": "query", "description": "Post-type filter (standard|hottake). hottake matches posts with isHotTake or postType=hottake; standard excludes them. Unknown values are ignored.", "schema": { "type": "string", "enum": [ "standard", "hottake" ] } } ], "security": [ {}, { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { posts, hasMore, nextCursor?, rankVersion? } } — posts on ranked filters also carry `rank` and `reason` (#686)" }, "400": { "description": "Invalid cursor — malformed, filter mismatch, or scope mismatch (teamId/phase/postType/authorTeamId/authorId/includeDemo changed between pages). Restart from page 1. A cursor whose anchor post was deleted or aged out of the ranking window is NOT a 400: the ranked filters resume from the anchor's own sort position instead. (VALIDATION_ERROR)" } } }, "post": { "tags": [ "Locker room" ], "summary": "Create locker room post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "imageUrl": { "type": "string" }, "teamId": { "type": "string", "description": "About-tag team" }, "authorTeamId": { "type": "string", "description": "Post-as-team identity" }, "postAsTeamId": { "type": "string", "description": "Native alias for authorTeamId" }, "scheduledFor": { "type": "string", "format": "date-time", "description": "Scheduled publish date (ISO 8601)" }, "privacy": { "type": "string", "enum": [ "public", "private" ] }, "media": { "type": "array", "items": { "type": "object" } }, "poll": { "type": "object" }, "collectible": { "type": "object" }, "lineup": { "type": "object", "description": "Formation builder attachment", "properties": { "presetKey": { "type": "string" }, "assignments": { "type": "object" }, "faces": { "type": "array", "items": { "type": "string" } } } }, "mentionedUserIds": { "type": "array", "nullable": true, "description": "User ids to tag. Self, unknown, blocked, and private non-followers are dropped. Over-cap ids past 10 are truncated. Null is treated as omit.", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Content is required (VALIDATION_ERROR), or scheduledFor is not a valid date (INVALID_SCHEDULE)." }, "403": { "description": "UGC terms not accepted. Envelope: { success: false, code: UGC_TERMS_REQUIRED, error }. Native composers reopen the terms modal on this code." } }, "description": "Create a post. content may be empty when media, poll, collectible, or lineup is present. teamId is the about-tag. authorTeamId / postAsTeamId is who the post is authored as (403 if unauthorized). lineup is persisted: { presetKey, assignments, faces }. Optional mentionedUserIds are resolved and echoed as mentions[] ({ id, handle, name?, profileUrl? }[]). A malformed mentionedUserIds is 400. The write stores tags with notifiedAt null and does not call OneSignal. GET /api/cron/locker-room-post-mentions sends SOCIAL_MENTION once the post is visible (scheduledFor null or already past), using dedupe key mention:post:{postId}:{userId}. Rejects with UGC_TERMS_REQUIRED when the caller's ugcTermsVersion is missing or not equal to the current Terms of Use version." } }, "/api/locker-room/comments/{commentId}/like": { "post": { "tags": [ "Locker room" ], "summary": "Toggle comment like", "description": "Authenticated like toggle on a locker-room comment.", "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/locker-room/hot-takes": { "get": { "tags": [ "Locker room" ], "summary": "List hot takes", "description": "Public-ish locker-room hot-take cards for discovery surfaces.", "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/locker-room/posts/draft": { "get": { "tags": [ "Locker room" ], "summary": "Get locker room draft", "description": "Authenticated composer draft. 404 if none exists.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "404": { "description": "No draft" } } }, "put": { "tags": [ "Locker room" ], "summary": "Upsert locker room draft", "description": "Body may include content, privacy, media, poll, collectible, channel. Returns { id, updatedAt }.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "delete": { "tags": [ "Locker room" ], "summary": "Delete locker room draft", "description": "204 even if no draft existed.", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Deleted or already absent" } } } }, "/api/locker-room/stream": { "get": { "tags": [ "Locker room" ], "summary": "Locker room SSE stream", "parameters": [ { "name": "filter", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "SSE stream" } } } }, "/api/locker-room/{id}": { "get": { "tags": [ "Locker room" ], "summary": "Get a single locker room post", "description": "Returns one post, including mentions[] ({ id, handle, name?, profileUrl? }[], empty when nobody is tagged). Users blocked with the viewer and null-handle users are omitted.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" }, "404": { "description": "Post not found" } } }, "put": { "tags": [ "Locker room" ], "summary": "Update locker room post content", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "mentionedUserIds": { "type": "array", "nullable": true, "description": "Omit or null leaves existing tags unchanged. [] clears them. A non-array is 400.", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { id, content, updatedAt, mentions } }" }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not post owner" }, "404": { "description": "Post not found" } } }, "delete": { "tags": [ "Locker room" ], "summary": "Delete locker room post", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { ok: true } }" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not post owner" }, "404": { "description": "Post not found" } } } }, "/api/locker-room/{id}/comments": { "get": { "tags": [ "Locker room" ], "summary": "Get post comments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "Locker room" ], "summary": "Add comment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "parentId": { "type": "string", "description": "Parent comment id for nested replies" }, "mentionedUserIds": { "type": "array", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "403": { "description": "UGC terms not accepted. Envelope: { success: false, code: UGC_TERMS_REQUIRED, error }. Native composers reopen the terms modal on this code." } }, "description": "Add a comment (or reply via parentId). Body accepts optional mentionedUserIds; responses echo mentions[] per resolved target. Rejects with UGC_TERMS_REQUIRED when the caller's ugcTermsVersion is missing or not equal to the current Terms of Use version." } }, "/api/locker-room/{id}/like": { "post": { "tags": [ "Locker room" ], "summary": "Toggle post like", "description": "Additive like toggle. Does not replace /react. Returns { liked, likeCount }.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/locker-room/{id}/poll/vote": { "post": { "tags": [ "Locker room" ], "summary": "Vote on a post poll", "description": "Authenticated poll vote for the post.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/locker-room/{id}/react": { "get": { "tags": [ "Locker room" ], "summary": "Get reactions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "Locker room" ], "summary": "Add reaction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/logout": { "get": { "tags": [ "Logout" ], "summary": "Logout (redirect)", "description": "Redirects to login.", "security": [], "responses": { "302": { "description": "Redirect to /login" } } }, "post": { "tags": [ "Logout" ], "summary": "Logout", "description": "Signs out the user.", "security": [], "responses": { "200": { "description": "{ success: true }" } } } }, "/api/mobile/callback": { "get": { "tags": [ "Mobile auth" ], "summary": "Mobile OAuth callback", "description": "Callback with redirect_uri. Returns token or error in redirect.", "parameters": [ { "name": "redirect_uri", "in": "query", "schema": { "type": "string" } } ], "security": [], "responses": { "302": { "description": "Redirect with token or error" } } } }, "/api/mobile/exchange": { "post": { "tags": [ "Mobile auth" ], "summary": "Exchange mobile session token for Clerk ticket", "description": "One-time redeem of a Prisma MobileSession hex token (body `{ token }` or Authorization Bearer) for a Clerk sign-in ticket. No Clerk session required. Consumes the mobile session.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[0-9a-fA-F]{128}$", "description": "64-byte mobile session token as 128 hex chars" } } } } } }, "responses": { "200": { "description": "{ success: true, data: { ticket, expiresAt } }" }, "400": { "description": "{ success: false, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, code: UNAUTHORIZED }" }, "500": { "description": "{ success: false, code: INTERNAL_ERROR }" } } } }, "/api/mobile/start": { "get": { "tags": [ "Mobile auth" ], "summary": "Start mobile OAuth", "description": "Redirects to mobile auth. Query: provider, redirect_uri.", "parameters": [ { "name": "provider", "in": "query", "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "schema": { "type": "string" } } ], "security": [], "responses": { "302": { "description": "Redirect to /mobile-auth" } } } }, "/api/mobile/verify": { "get": { "tags": [ "Mobile auth" ], "summary": "Verify mobile token", "description": "Verifies Bearer token from native app.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, user }" } } } }, "/api/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List notifications", "description": "Authenticated inbox. Query: page, limit (max 100), status (ALL | UNREAD | READ | ARCHIVED). Includes GAME_ALERT and RATING types.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ALL | UNREAD | READ | ARCHIVED" } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/notifications/read-all": { "post": { "tags": [ "Notifications" ], "summary": "Mark all notifications read", "description": "Authenticated mark-all-read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/notifications/{notificationId}/archive": { "post": { "tags": [ "Notifications" ], "summary": "Archive notification", "description": "Authenticated single-item archive.", "parameters": [ { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/notifications/{notificationId}/read": { "post": { "tags": [ "Notifications" ], "summary": "Mark notification read", "description": "Authenticated single-item read.", "parameters": [ { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/packs": { "get": { "tags": [ "Packs" ], "summary": "List active packs", "description": "Each pack row includes template and art fields (PackGlbMedia). modelUrl falls back to animationId only when modelUrl is null.", "security": [], "responses": { "200": { "description": "{ packs }" } } } }, "/api/packs/free-status": { "get": { "tags": [ "Packs" ], "summary": "Get per-team free-pack status", "description": "Authenticated per-user read of free-pack state for the current UTC day, without hitting the cap. Without teamId, one row per team with an active, non-internal, currently-released free pack. With teamId, that team row, or an empty teams array when the team has no active free pack (never 404: native treats 404 as route-not-deployed and hides the clock). Counts share the where clause the 429 path enforces, so remaining matches the cap; purchase and checkout re-count under lock and stay authoritative. Cache-Control: no-store. No quiet-hours window exists yet, so none is honored (#914 follow-up).", "parameters": [ { "name": "teamId", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { teams: [{ teamId, limit, used, remaining, resetsAt }] } }. resetsAt is next UTC midnight, ISO 8601, same value as the 429 resetsAt." }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" } } } }, "/api/packs/feed": { "get": { "tags": [ "Packs" ], "summary": "Live pull feed", "description": "Clerk auth required (401 anonymous). One item per drawn card, newest first: { id: ::, pulledAt, rarity, card: { id (collectible slug), name, imageUrl }, team: { id, name } | null, pack: { id, name, slug }, user: { id, handle, avatarUrl } | null }. The slot is the position in the open's drawn cards, so repeated draws of one card stay distinct. user is null when the account exists but the handle is gone; deleted accounts are excluded. user.id targets POST /api/moderation/reports targetUserId. Query: cursor (opaque nextCursor; page boundaries inside one open resume exactly), limit (default 20, max 50), teamId (id or slug; absent = global), minRarity (default RARE; RARE|EPIC|LEGENDARY|MYTHIC, COMMON explicit-only), includeFree (default false). Server-side-only filtering: opted-out (privateProfile incl. User.isPrivate mirror, !showCollectibles, !showPullsInFeed), blocked both directions, viewer-muted, internalOnly always and price=0 unless includeFree, below minRarity, newer than the 30 s publish delay, admin-hidden via upheld (RESOLVED) user-scoped moderation reports (post/comment-scoped reports sanction that content, not the pulls). Cache: private, max-age=10, stale-while-revalidate=10 + ETag (304 on If-None-Match). (#883, #896)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque nextCursor from a prior response." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 } }, { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Team id or slug; absent = global." }, { "name": "minRarity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "RARE", "EPIC", "LEGENDARY", "MYTHIC", "COMMON" ], "default": "RARE" } }, { "name": "includeFree", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "{ success, data: { items: FeedPull[], nextCursor: string | null } }" }, "400": { "description": "Invalid cursor or minRarity." }, "401": { "description": "Anonymous (Clerk auth required)." } } } }, "/api/packs/scene-version": { "get": { "tags": [ "Packs" ], "summary": "Active pack scene versions and hashes", "description": "Unauthenticated, read-only. For pack-open-scene and collectible-spin-scene: the highest ACTIVE RenderTemplate version, its bundleSha256, and the sceneSha256 of the scene page it ships, so clients can detect drift against their embedded scene. 500 (SCENE_VERSION_UNRESOLVED) if a key has no active row or the active version is missing from the generated scene map; never a partial or guessed hash. Cache: public, s-maxage=60. (#900)", "security": [], "responses": { "200": { "description": "{ success, data: { packOpenScene: SceneVersion, collectibleSpinScene: SceneVersion } } where SceneVersion = { version: integer, sceneSha256: string, bundleSha256: string }" }, "500": { "description": "Active version could not be resolved to a hash." } } } }, "/api/packs/{id}": { "get": { "tags": [ "Packs" ], "summary": "Get pack by ID", "description": "The pack row includes template and art fields (PackGlbMedia). modelUrl falls back to animationId only when modelUrl is null.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pack object" } } } }, "/api/packs/{id}/open": { "post": { "tags": [ "Packs" ], "summary": "Open pack", "description": "Body is optional; a blank body is {}. Shape: { purchaseId?: string, packId?: string, binderId?: string, walletAddress?: string }. Each field must be a string when present. walletAddress is the active wallet: with no binder chosen the open lands in that wallet's default binder (#928). Malformed JSON, a non-object body, or a non-string field is 400 VALIDATION_ERROR. Client-sent rarities are ignored. Success data adds bonus: null | { purchaseId, rarity, requested, awarded, alreadyApplied }. Success data also adds pack: PackGlbMedia plus id, on first open and on replays. glbTemplateVersion is null when undeclared (clients fail closed). 0 means materials FRONT and BACK. Each collectibles[] item carries serial: CardSerial | null — FINITE packs return the claimed MintInstance serialNo with total = the pack's mint count for that card; unlimited packs return the next per-collectible number with total null; null only on replays of copies opened before serials existed. When the pack has guaranteeMinRarity, one card at or above that rarity is drawn and placed in a random slot, and the rest are drawn at the listed odds; if the contents can't meet the guarantee the open fails with 409 CONFLICT and the pack stays unopened. Each collectibles[] item carries value: integer | null and valueBreakdown: CardValueBreakdown | null (display value from the current tables, on first open and on replays). Each collectibles[] item carries player: CardPlayer | null (first open and replays): the roster player linked to the collectible; null when none is linked. Each collectibles[] item carries isNew and isDuplicate (boolean or null): opposites when this open stored a collection summary, null when no summary was stored. data.collection is null on a replay with no summary. A fresh open always sends { alreadyApplied: false, setDeltas }. setDeltas lists sets whose owned count changed, with newlyCompleted and a cosmetic reward when this open granted the badge. A replay with a summary returns the stored flags and setDeltas with alreadyApplied true, not a fresh inventory read (#915).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "Optional. A blank body is treated as {}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseId": { "type": "string" }, "packId": { "type": "string", "description": "Optional. Legacy clients may send path as packId + body.purchaseId." }, "binderId": { "type": "string", "description": "Optional landing binder. Client-sent rarities are ignored." }, "walletAddress": { "type": "string", "description": "Optional active wallet. With no binder chosen the open lands in this wallet's default binder (#928)." } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ collectibles, mintedNftIds, landedBinderId, bonus, rep, pack, autoSort }. autoSort is null when pack auto-sort is off or the pack is internal-only; otherwise { applied, source, binder: { id, name, isDefault }, placedCount, newCount, duplicateCount, fallbackReason, scopeMismatchCount }. applied is true when the pref is on and the cards landed in the destination: a preference or default landing, or a checkout landing whose target equals the pref binder (or the default binder when packAutoSortBinderId is null). source stays checkout for that landing. An explicit binder stays applied false. collection is null or { alreadyApplied, setDeltas } (#915).", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "collectibles", "mintedNftIds", "landedBinderId", "bonus", "pack", "rep", "collection" ], "properties": { "collectibles": { "type": "array", "items": { "type": "object", "required": [ "serial", "player", "value", "valueBreakdown", "isNew", "isDuplicate", "finish", "cardTemplate" ], "properties": { "serial": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CardSerial" } ] }, "value": { "type": [ "integer", "null" ], "minimum": 0, "description": "Display value in points. Null only when the value tables could not be read." }, "valueBreakdown": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CardValueBreakdown" } ] }, "player": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CardPlayer" } ] }, "isNew": { "type": [ "boolean", "null" ], "description": "True when this pull was the fan's first copy of the card. Null when no collection summary was stored." }, "isDuplicate": { "type": [ "boolean", "null" ], "description": "Opposite of isNew when the flag is known. Null when isNew is null." }, "finish": { "type": [ "string", "null" ], "description": "Card finish id, or null when no finish is set." }, "cardTemplate": { "description": "Null when the card image has no verifiable published render.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CardTemplate" } ] } } } }, "mintedNftIds": { "type": "array", "items": { "type": "string" } }, "landedBinderId": { "type": "string" }, "bonus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PackOpenBonusDto" } ] }, "pack": { "allOf": [ { "$ref": "#/components/schemas/PackGlbMedia" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } ] }, "rep": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PackOpenRepDto" } ] }, "collection": { "description": "Null when this replay has no stored summary. Fresh opens always send the object.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "alreadyApplied", "setDeltas" ], "properties": { "alreadyApplied": { "type": "boolean" }, "setDeltas": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionSetDelta" } } } } ] }, "gameServices": { "description": "Present only for a fresh open; replays omit the whole block. Optional hints are omitted individually when unavailable.", "type": "object", "properties": { "firstEver": { "type": "boolean", "description": "Present when the first-open milestone claim succeeds." }, "fanPoints": { "type": "object", "description": "Present when the Fan Rep lookup succeeds.", "required": [ "total", "seasonTotal" ], "properties": { "total": { "type": "integer" }, "seasonTotal": { "type": [ "integer", "null" ] } } } } } } } } } } } }, "400": { "description": "{ success: false, error, code } — VALIDATION_ERROR when the body is malformed JSON, is not a JSON object, or a present purchaseId, packId, or binderId is not a string. The same status also carries PACK_PAYMENT_PENDING, PACK_ALREADY_OPENED, PACK_NOT_READY for failed, cancelled or refunded purchases, WALLET_REQUIRED, and VALIDATION_ERROR for an unrecognised purchase status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "description": "VALIDATION_ERROR for a rejected body. Other pack-open 400 codes use the same envelope." } } } } } } } } }, "/api/packs/{id}/purchase": { "post": { "tags": [ "Packs" ], "summary": "Start pack purchase", "description": "Body: { paymentMethod: 'crypto' | 'dsports-cash', walletAddress?: string }. walletAddress is the active wallet, recorded on the purchase so the open lands in its default binder (#928). Omitted resolves to the fan's primary wallet (oldest custodial, else oldest of any type), or null when the fan has no wallet (#938).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "crypto", "dsports-cash" ] }, "walletAddress": { "type": "string", "description": "Optional active wallet recorded on the purchase (#928). Omitted resolves to the fan's primary wallet (oldest custodial, else oldest of any type), or null when the fan has no wallet (#938)." } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ purchaseId }" }, "403": { "description": "WALLET_NOT_LINKED — active wallet no longer linked to the fan. Legacy FORBIDDEN with the same message is still possible from older deploys." } } }, "put": { "tags": [ "Packs" ], "summary": "Complete pack purchase (removed)", "description": "Removed in v0.2.0 (#709 Gap 1): always 410 GONE. Purchase confirmation moved to checkout verify (POST /api/checkout/crypto/verify). Kept as 410 (not 405) for one release so stale clients get a routable error.", "deprecated": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseId": { "type": "string" }, "paymentIntentId": { "type": "string" }, "transactionHash": { "type": "string" } } } } } }, "security": [], "responses": { "410": { "description": "{ error, code: GONE } — use POST /api/checkout/crypto/verify" } } } }, "/api/products": { "get": { "tags": [ "Products", "Commerce and purchases" ], "summary": "List products", "description": "Pack items' metadata carries PackGlbMedia plus glbUrlWeb and glbUrlNative (both the served modelUrl). animationId stays. modelUrl prefers Pack.modelUrl and falls back to animationId only when that column is null.", "security": [], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "teamId", "in": "query", "description": "Team id or slug.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Product or pack id or slug. 404 when it does not resolve.", "schema": { "type": "string" } }, { "name": "slug", "in": "query", "description": "Product or pack slug (same resolution as id).", "schema": { "type": "string" } }, { "name": "rarity", "in": "query", "description": "Canonical rarity (common, rare, epic, legendary, mythic) or the stored string. Cuid values match nothing.", "schema": { "type": "string" } }, { "name": "featured", "in": "query", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Products and packs" }, "404": { "description": "id or slug did not resolve to a product or pack" } } } }, "/api/quests": { "get": { "tags": [ "Quests", "Gamification" ], "summary": "Get quests", "description": "Query: category (optional) for QuestCategory; else active quests.", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ quests, currentUserId }" }, "401": { "description": "Authentication required" } } } }, "/api/quests/check-progress": { "post": { "tags": [ "Quests" ], "summary": "Check quest progress", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "questType": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success }" } } } }, "/api/quests/complete-step": { "post": { "tags": [ "Quests" ], "summary": "Complete quest step", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "questId": { "type": "string" }, "stepId": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, pointsAwarded, questCompleted, gameServices?: { firstEver?, fanPoints? } }. firstEver is true exactly once: the first delivery to the client of the fan's first-quest milestone (which may have been recorded earlier by a background completion); it is false otherwise and omitted if best-effort delivery fails. fanPoints is present only when its lookup succeeds." } } } }, "/api/quests/daily-visit": { "post": { "tags": [ "Quests" ], "summary": "Daily visit", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Daily visit result" } } } }, "/api/quests/start": { "post": { "tags": [ "Quests" ], "summary": "Start quest", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "questId": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ quest, success }" } } } }, "/api/rewards": { "get": { "tags": [ "Rewards", "Gamification" ], "summary": "List rewards", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ rewards, currentUserId }" } } } }, "/api/rewards/claim": { "post": { "tags": [ "Rewards" ], "summary": "Claim reward", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rewardId": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ reward, success }" } } } }, "/api/rewards/redeem": { "post": { "tags": [ "Rewards" ], "summary": "Redeem reward", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rewardId": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ reward, success }" } } } }, "/api/sync-quest-points": { "post": { "tags": [ "Misc", "Platform and infrastructure" ], "summary": "Sync quest points", "description": "Internal maintenance route for quest/points reconciliation.", "x-hidden": true, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/teams": { "get": { "tags": [ "Teams" ], "summary": "List teams", "description": "List teams with enriched stats, or look up one team with ?slug=. Archived slugs 404 regardless of casing. Payload includes fans, totalPoints, rank, lastWinner, isOfficial, league, themeColor, leaderboardId, leagueInfo, leagueColors, never-null sport, plus _count { packs, collectibles }. logo is the raster crest (logoPng when the stored logo is SVG, else logo); logoSvg carries the stored vector logo when a logoPng sibling exists, else null. Joinability: joinable (boolean), isGlobal (boolean), teamCategory (e.g. dsports_official). D-Sports is joinable:false / isGlobal:true / teamCategory:\"dsports_official\" — not a club membership board. source (dsports = partner club with the full social surface; provider = pulled data-only HQ) and providerId (api-sports team id, the dedupe key) are included per team. rosterVerifiedByClubAt is an ISO-8601 timestamp or null (null until a club admin confirms the roster). nickname is the admin-set short club name (for example Milano for Milano HC), or null when unset; clients then derive the short name from name. ?leagueId= filters, ?search= matches name/slug server-side, ?limit=/?page= paginate (opt-in; omitted returns the whole filtered list with { teams, season, total }).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { teams, season, total } } (total always present when filtering/paginating; absent on the unfiltered full-list call) or { success, data: { team } } when slug is set" } }, "parameters": [ { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Single-team lookup. Returns { team }." }, { "name": "leagueId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to one league (relation id or slug)." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Server-side name/slug match." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size 1-100. Pagination is opt-in." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "1-based page." } ] } }, "/api/teams/{id}": { "get": { "tags": [ "Teams" ], "summary": "Get team by id or slug", "description": "Public. Fetch a single team by id or slug (id is tried first). Same shape as an entry in GET /api/teams plus teamRecord, foundedDate, viewerCanPostAsTeam and seasonState. Includes rosterVerifiedByClubAt (ISO-8601 or null). seasonState ({ state: in_season | off_season | preseason, hubEnabled }) is the off-season hub gate (#999): native flips SHOW_OFFSEASON_HUB off seasonState.hubEnabled instead of a client constant. Archived teams 404. 400 without an id, 404 for unknown teams.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { team } } — team.seasonState is always present." }, "400": { "description": "VALIDATION_ERROR" }, "404": { "description": "Team not found" } } } }, "/api/teams/{id}/head-to-head": { "get": { "tags": [ "Teams" ], "summary": "Head-to-head series vs an opponent", "description": "Public. { record: { wins, losses, ties }, meetings: [{ gameId, date, homeAbbr, awayAbbr, homeScore, awayScore }] } from the perspective of {id}. The 5 most recent decided meetings (live games excluded so the list and the record agree). Empty history is a valid 200. 400 without opponentId, 404 for unknown teams.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "opponentId", "in": "query", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { record, meetings } }" }, "400": { "description": "opponentId missing or equals teamId" }, "404": { "description": "Team not found" } } } }, "/api/events/{gameId}/player-stats": { "get": { "tags": [ "Events" ], "summary": "Per-player box score", "description": "Public. { columns: [{ key, label }], players: [{ playerKey, playerId?, name, teamSide, position?, jersey?, didNotPlay?, stats: [{ key, label, value }] }] }. Columns are server-driven (hockey: G/A/PTS/PIM). playerKey matches LineupSlot.playerKey when linkable. { columns: [], players: [] } is a valid 200 for games with no player data.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { columns, players } }" }, "404": { "description": "Game not found" } } } }, "/api/events/{gameId}/win-probability": { "get": { "tags": [ "Events" ], "summary": "Odds-implied win probability", "description": "Public. { home, away } always sums to 100; model is final (decided game) | odds-implied (bookmaker winner market) | even (no usable market — honest 50/50). Same poll cadence as box-score stats.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { home, away, model, bookmaker? } }" }, "404": { "description": "Game not found" } } } }, "/api/events/{gameId}/top-performer": { "get": { "tags": [ "Events" ], "summary": "Top performer per side", "description": "Public. { home: { playerKey, playerId, name, pos, jersey, avatar, statLine } | null, away: ... | null }. playerKey is the Game Center identity (same key space as LineupSlot.playerKey); playerId is the linked roster id or null. statLine is sport-formatted server-side (hockey: \"2G 1A\"). Null per side when there is no candidate.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { home, away } }" }, "404": { "description": "Game not found" } } } }, "/api/admin/players/{playerId}/availability": { "put": { "tags": [ "Admin" ], "summary": "Set player availability", "description": "Platform admin. Manual availability/injury entry (no hockey provider supplies this). Null status clears back to available.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": [ "string", "null" ], "enum": [ "out", "day-to-day", "injured-reserve", "suspended", "questionable", null ] }, "detail": { "type": [ "string", "null" ] }, "expectedReturn": { "type": [ "string", "null" ] } } } } } }, "parameters": [ { "name": "playerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { id } }" }, "400": { "description": "Invalid status/date" }, "404": { "description": "Player not found" } } } }, "/api/teams/followed": { "get": { "tags": [ "Teams" ], "summary": "List followed teams", "description": "Teams the authenticated user follows.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/teams/search": { "get": { "tags": [ "Teams" ], "summary": "Search teams", "description": "Cursor-paginated team search. Query: q (max 64), sport, league, cursor, limit (1-50), sort (rank | name | fans). Each team includes rosterVerifiedByClubAt (ISO-8601 or null) and nickname (admin-set short club name, or null to derive it from name).", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sport", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "league", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "rank | name | fans" } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/teams/{id}/follow": { "get": { "tags": [ "Teams" ], "summary": "Get follow status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "Teams" ], "summary": "Follow team", "description": "Body optional: { type?: 'followed' | 'fan' }. Platform / non-joinable teams (D-Sports slug, joinable:false, isGlobal, teamCategory dsports_official / platform) return 409 CONFLICT and do not write TeamFollow.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "followed", "fan" ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success }" }, "409": { "description": "CONFLICT — platform / non-joinable team cannot be followed. No TeamFollow write." } } }, "delete": { "tags": [ "Teams" ], "summary": "Unfollow team", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success }" } } } }, "/api/teams/{id}/join": { "post": { "tags": [ "Teams" ], "summary": "Join team leaderboard", "description": "Idempotent leaderboard membership only. Does not write TeamFollow. Returns { joinedTeamIds, followedTeamIds }. Joining a platform / non-joinable team (D-Sports slug, joinable:false, isGlobal, dsports_official) returns 409 CONFLICT before any board or entry write.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "409": { "description": "CONFLICT — platform / non-joinable team cannot be joined. No board or entry write." } } }, "delete": { "tags": [ "Teams" ], "summary": "Leave team leaderboard", "description": "Idempotent. Removes only the club leaderboard entry. Social follow stays in place. Leave on a platform / non-joinable team (D-Sports slug, joinable:false, isGlobal, dsports_official) is a no-op (no entry write). Returns { joinedTeamIds, followedTeamIds }.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/teams/{id}/roster": { "get": { "tags": [ "Teams" ], "summary": "Get team roster", "description": "Public real-player roster for the lineup builder. { rosterVerifiedByClubAt: ISO-8601 | null, players: [{ id, name, jersey, position, role, duty, photo? }] }. rosterVerifiedByClubAt is null until a club admin confirms the roster. `photo` is omitted when the player has no art. `availability?` ({ status: out|day-to-day|injured-reserve|suspended|questionable, detail?, expectedReturn?, updatedAt? }) is a player-level field, omitted entirely when the player is available. ?season= is accepted and echoed; the roster is a DB snapshot with no season axis, so every season reads the same list. 404 if team is missing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "season", "in": "query", "required": false, "description": "Season start year (2026 = 2026-27). Accepted and echoed; the roster has no season axis.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } } ], "security": [], "responses": { "200": { "description": "{ success, data: { rosterVerifiedByClubAt, players, season? } }" }, "400": { "description": "Invalid season" }, "404": { "description": "Team not found" } } } }, "/api/teams/{id}/statistics": { "get": { "tags": [ "Teams" ], "summary": "Get team season statistics", "description": "HQ club statistics tab (#848). Public. { teamId, season, games: { played, wins, losses, otLosses, ties }, goals: { for, against, forPerGame, againstPerGame }, splits: { home, away }, otWins, periodGoals }. Vendor-cached reads at the team-stats TTL (hourly, same policy as standings). Unmapped teams and vendor misses serve zeroed figures. 404 only for a missing team (or a missing ?leagueId= league). Odds are intentionally not served (see docs/hq-odds-blocked.md).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "season", "in": "query", "required": false, "description": "Season start year (2026 = 2026-27). Defaults to the current hockey season.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "leagueId", "in": "query", "required": false, "description": "Prisma League.id or slug scoping the vendor read. Defaults to the team's league.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { teamId, season, games, goals, splits, otWins, periodGoals } }" }, "400": { "description": "Invalid season" }, "404": { "description": "Team or league not found" } } } }, "/api/teams/{id}/lineup": { "get": { "tags": [ "Teams" ], "summary": "Get team official lineup", "description": "Public official lineup for the lineup builder (#847). { teamId, presetKey, assignments: [{ slotKey, playerId }], source: official|derived, updatedAt: ISO-8601|null, rosterVerifiedByClubAt: ISO-8601|null }. Club-saved rows win; without one the starters derive from the active roster. Stored assignments for departed players are dropped. presetKey/slotKey are opaque native-owned strings. 404 for unknown teams.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { teamId, presetKey, assignments, source, updatedAt, rosterVerifiedByClubAt } }" }, "400": { "description": "VALIDATION_ERROR" }, "404": { "description": "Team not found" } } }, "put": { "tags": [ "Teams" ], "summary": "Save team official lineup", "description": "Team-admin write path for the official lineup (#847). Body: { presetKey, assignments: [{ slotKey, playerId }] } - every playerId must be an active roster row on this team. Owner, editor, legacy admin, or platform admin. Upserts the single per-team row.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "presetKey", "assignments" ], "properties": { "presetKey": { "type": "string" }, "assignments": { "type": "array", "items": { "type": "object", "required": [ "slotKey", "playerId" ], "properties": { "slotKey": { "type": "string" }, "playerId": { "type": "string" } } } } }, "description": "{ presetKey, assignments: [{ slotKey, playerId }] }" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: lineup }" }, "400": { "description": "ROSTER_INVALID for an unknown or inactive player, with details: { reason: PLAYER_NOT_ON_ACTIVE_ROSTER, playerId }; otherwise VALIDATION_ERROR" }, "401": { "description": "Authentication required" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "Team not found" } } }, "delete": { "tags": [ "Teams" ], "summary": "Clear team official lineup", "description": "Removes the official lineup; reads revert to the roster-derived fallback (#847). Same managers as PUT. Idempotent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { teamId, cleared } }" }, "401": { "description": "Authentication required" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "Team not found" } } } }, "/api/teams/{id}/players/season-stats": { "get": { "tags": [ "Teams" ], "summary": "Get team player season stats", "description": "Public. Per-player season rollup from the API-Sports event feed (league games only, friendlies excluded). derived = feed counts; effective = { ...derived, ...override } (gamesPlayed falls back to gamesCounted, points = effective goals + assists); overridden lists the override keys. id is a team id or slug. Edge-cached 60s. Sorted by effective points, goals, name.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "season", "in": "query", "required": false, "description": "Season start year (2026 = 2026-27). Defaults to the current hockey season.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } } ], "security": [], "responses": { "200": { "description": "{ success, data: { teamId, season, players } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "teamId", "season", "players" ], "properties": { "teamId": { "type": "string" }, "season": { "type": "integer" }, "players": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerSeasonStatRow" } } } } } } } } }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR } — bad season" }, "404": { "description": "Team not found" } } } }, "/api/admin/teams/{teamId}/analytics": { "get": { "tags": [ "Admin", "Teams" ], "summary": "Team analytics and revenue (admin)", "description": "One payload for the web Analytics and Revenue tabs and native d-sports-engage-native#1245 (Analytics) and #1246 (Revenue). Gate: canAccessTeam (decided 2026-11-11, Option A), also re-checked inside getTeamAnalytics. Owner, editor, viewer and legacy admin members of the team, plus platform admin/superadmin, get 200; outsiders 403 FORBIDDEN; anonymous 401. Web and native hide the Analytics and Revenue rows from editors and viewers in the UI only; do not tighten the server check to owner-only. `period` is 7d, 30d or all; missing or invalid values become 30d (never 400). Totals and trends are lifetime or last 6 months; `period` only sets the comparison window of followerGrowth30d, packGrowth30d and revenueGrowth30d and is echoed as overview.period. Revenue is DSC only; only completed or opened purchases count. There is no pagination and no server export route: web Revenue export is a client-side CSV built from packStats. Response is `Cache-Control: private, no-store`.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id or slug." }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "all" ], "default": "30d" }, "description": "Growth comparison window. Any other value is treated as 30d." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: TeamAnalytics }. Dates are ISO 8601 strings.", "headers": { "Cache-Control": { "description": "Team revenue data must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "overview", "followerTrend", "monthlyRevenue", "topPerformers", "revenueByCategory", "packStats", "collectibleStats", "recentActivity", "rarityDistribution" ], "properties": { "overview": { "type": "object", "required": [ "totalPacks", "totalCollectibles", "totalRevenue", "totalFollowers", "totalFans", "totalMembers", "totalCollectors", "avgCollectionSize", "activeDrops", "scheduledDrops", "totalPacksSold", "totalPacksOpened", "packRevenue", "productRevenue", "avgSalePrice", "followerGrowth30d", "packGrowth30d", "revenueGrowth30d", "period" ], "properties": { "totalPacks": { "type": "number" }, "totalCollectibles": { "type": "number" }, "totalRevenue": { "type": "number" }, "totalFollowers": { "type": "number" }, "totalFans": { "type": "number" }, "totalMembers": { "type": "number" }, "totalCollectors": { "type": "number" }, "avgCollectionSize": { "type": "number" }, "activeDrops": { "type": "number" }, "scheduledDrops": { "type": "number" }, "totalPacksSold": { "type": "number" }, "totalPacksOpened": { "type": "number" }, "packRevenue": { "type": "number" }, "productRevenue": { "type": "number" }, "avgSalePrice": { "type": "number" }, "followerGrowth30d": { "type": "number" }, "packGrowth30d": { "type": "number" }, "revenueGrowth30d": { "type": "number" }, "period": { "type": "string", "enum": [ "7d", "30d", "all" ] } } }, "followerTrend": { "type": "array", "items": { "type": "object", "required": [ "month", "value" ], "properties": { "month": { "type": "string" }, "value": { "type": "number" } } } }, "monthlyRevenue": { "type": "array", "items": { "type": "object", "required": [ "month", "revenue" ], "properties": { "month": { "type": "string" }, "revenue": { "type": "number" } } } }, "topPerformers": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "rarity", "sold", "revenue", "priceEach" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rarity": { "type": "string" }, "sold": { "type": "number" }, "revenue": { "type": "number" }, "priceEach": { "type": "number" } } } }, "revenueByCategory": { "type": "array", "items": { "type": "object", "required": [ "category", "amount", "percentage" ], "properties": { "category": { "type": "string" }, "amount": { "type": "number" }, "percentage": { "type": "number" } } } }, "packStats": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "image", "imageThumbhash", "price", "internalOnly", "quantity", "sold", "opened", "revenue", "status", "releaseDate" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "imageThumbhash": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "internalOnly": { "type": "boolean", "description": "Internal grant pack. Label Granted when true; Free when price is 0; otherwise paid." }, "quantity": { "type": "number" }, "sold": { "type": "number" }, "opened": { "type": "number" }, "revenue": { "type": "number" }, "status": { "type": "string", "enum": [ "Scheduled", "Active", "Paused", "Expired", "Ended" ] }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time" } } } }, "collectibleStats": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "image", "imageThumbhash", "rarity", "supply", "minted", "distributed", "createdAt" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "imageThumbhash": { "type": [ "string", "null" ] }, "rarity": { "type": "string" }, "supply": { "type": "number" }, "minted": { "type": "number" }, "distributed": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "recentActivity": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "title", "description", "timestamp" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "pack_purchase", "pack_open", "product_purchase", "team_follow" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } }, "rarityDistribution": { "type": "array", "items": { "type": "object", "required": [ "rarity", "count", "percentage" ], "properties": { "rarity": { "type": "string" }, "count": { "type": "number" }, "percentage": { "type": "number" } } } } } } } } } } }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR } when the team id is missing; also a failure caught inside getTeamAnalytics (for example a database error), which has no code" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } } }, "/api/admin/teams/{teamId}/quests/{questId}": { "patch": { "tags": [ "Admin", "Teams" ], "summary": "Update team quest (admin)", "description": "Gate: canManageTeam (owner, editor, legacy admin, platform admin/superadmin). Viewers and outsiders get 403; anonymous 401. Every body field is optional; scalar-only bodies behave exactly as before. `steps` uses the same item shape as POST create: omitted leaves the quest's steps untouched, `[]` clears them, a list replaces them. Replacement runs in one transaction with the scalar edits under a row lock on the quest (scoped to quest id + team); step ids are always server-generated and `order` defaults to the item's index. If `steps` is supplied (including `[]` or an unchanged list) and ANY user has started the quest (a UserQuestStatus row exists), the request is refused with 409 CONFLICT and nothing is written, because deleting a QuestStep cascades to user step progress. Scalar-only edits stay allowed with progress. Response is `Cache-Control: private, no-store`.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id or slug." }, { "name": "questId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team-scoped (non-template) quest id." } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "points": { "type": "integer", "minimum": 0 }, "iconName": { "type": "string" }, "category": { "type": "string", "enum": [ "ONBOARDING", "SOCIAL", "ENGAGEMENT", "PURCHASE", "DAILY", "WEEKLY", "SPECIAL_EVENT" ] }, "cadence": { "type": [ "string", "null" ] }, "isRepeatable": { "type": "boolean" }, "cooldownHours": { "type": [ "integer", "null" ] }, "order": { "type": "integer" }, "isActive": { "type": "boolean" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "steps": { "type": "array", "description": "Omitted = keep current steps; [] = clear; list = replace atomically. 409 CONFLICT once any user has started the quest.", "items": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "description": "Trimmed; whitespace-only is rejected with 400." }, "description": { "type": "string" }, "order": { "type": "integer", "description": "Defaults to the item's index." }, "points": { "type": "integer", "description": "Defaults to 0." }, "stepCode": { "type": [ "string", "null" ] } } } } } } } } }, "responses": { "200": { "description": "{ success, data: TeamQuest } — the updated quest with steps ordered by `order` asc.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "id", "title", "steps" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "points": { "type": "integer" }, "iconName": { "type": "string" }, "category": { "type": "string" }, "isRepeatable": { "type": "boolean" }, "cooldownHours": { "type": [ "integer", "null" ] }, "isActive": { "type": "boolean" }, "order": { "type": "integer" }, "cadence": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "teamId": { "type": [ "string", "null" ] }, "isTemplate": { "type": "boolean" }, "sourceTemplateId": { "type": [ "string", "null" ] }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "steps": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "description", "order", "points", "stepCode" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "order": { "type": "integer" }, "points": { "type": "integer" }, "stepCode": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR } — malformed body or step (blank title, non-integer order/points). A failed transaction (nothing written) is also 400 with `error` and no `code`, preserving the existing route behavior." }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND } — quest is not a non-template quest of this team (including when deleted mid-request)." }, "409": { "description": "{ success: false, error, code: CONFLICT } — `steps` supplied but a UserQuestStatus exists for the quest. Nothing was written; retry without `steps` for scalar edits." }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } } }, "/api/admin/teams/{teamId}/members": { "get": { "tags": [ "Admin", "Teams" ], "summary": "List team members (admin)", "description": "Gate: canAccessTeam. Owner, editor, viewer and legacy admin members of the team, plus platform admin/superadmin, get 200; outsiders 403; anonymous 401. Rows are ordered by role asc then createdAt asc, unpaged. Each row keeps the TeamAdmin scalars (id, teamId, userId, role, createdAt) and adds `user` { id, handle, name, profileUrl }. Email is not returned. Response is `Cache-Control: private, no-store`.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id or slug." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: TeamMember[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "teamId", "userId", "role", "createdAt", "user" ], "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer", "admin" ], "description": "Legacy `admin` rows may still exist; treat as editor." }, "createdAt": { "type": "string", "format": "date-time" }, "user": { "type": "object", "description": "Display fields for the member (id, handle, name, profileUrl). Email is never returned.", "required": [ "id", "handle", "name", "profileUrl" ], "properties": { "id": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] } } } } } } } } } } }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } }, "post": { "tags": [ "Admin", "Teams" ], "summary": "Add team member (admin)", "description": "Gate: canManageTeam with owner or legacy admin on the team, or platform admin/superadmin. Editors and viewers get 403. Only platform admins may assign `owner`. Body `{ userId, role? }`, role defaults to editor. Missing userId is 400 \"userId is required\". Returns the TeamAdmin scalar row (no `user` object).", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id or slug." } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "string" }, "role": { "type": "string", "default": "editor" } } } } } }, "responses": { "201": { "description": "{ success, data: TeamAdmin }" }, "400": { "description": "{ success: false, error: \"userId is required\" }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } } }, "/api/admin/teams/{teamId}/members/candidates": { "get": { "tags": [ "Admin", "Teams" ], "summary": "Search fans to add as a team member (admin)", "description": "Gate: canManageTeam with owner or legacy admin on the team, or platform admin/superadmin (the same set as Add team member). Editors, viewers and outsiders get 403; anonymous 401. `q` is trimmed, 2-50 chars, matched case-insensitively against handle and name only (never email), with `%` and `_` literal. `limit` is an integer 1-10, default 5; out-of-range values are 400 VALIDATION_ERROR, not clamped. Fans who already hold a TeamAdmin row on the team are excluded. Ordered by handle ascending, unpaged. Each row is { id, handle, name, profileUrl }; email is never returned. Limited to 30 requests per 60s per caller once the gate passes (429 RATE_LIMITED); a limiter outage fails closed (503 RATE_LIMITER_UNAVAILABLE). Every response is `Cache-Control: private, no-store`.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id or slug." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 50 }, "description": "Search text, trimmed, matched against handle and name." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: FanCandidate[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "description": "Roster display shape. Email is never returned.", "required": [ "id", "handle", "name", "profileUrl" ], "properties": { "id": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "profileUrl": { "type": "string" } } } } } } } } }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "429": { "description": "{ success: false, error, code: RATE_LIMITED }" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" }, "503": { "description": "{ success: false, error, code: RATE_LIMITER_UNAVAILABLE }" } } } }, "/api/admin/teams/{teamId}/members/{userId}": { "patch": { "tags": [ "Admin", "Teams" ], "summary": "Change team member role (admin)", "description": "Gate: canManageTeam with owner only (legacy admin is 403), or platform admin/superadmin. Only platform admins may change to or from `owner`. Body `{ role }` with role owner|editor|viewer, otherwise 400 \"Invalid role\". 404 when the member does not exist.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id or slug." }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id of the member." } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ] } } } } } }, "responses": { "200": { "description": "{ success, data: TeamAdmin }" }, "400": { "description": "{ success: false, error: \"Invalid role\" }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } }, "delete": { "tags": [ "Admin", "Teams" ], "summary": "Remove team member (admin)", "description": "Gate: canManageTeam with owner only (legacy admin is 403), or platform admin/superadmin. Only platform admins may remove an owner. The last owner cannot be removed by themselves (400). No request body.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team id or slug." }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id of the member." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success: true, data: { success: true } }" }, "400": { "description": "{ success: false, error: \"Cannot remove the last owner\" }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } } }, "/api/admin/teams/{teamId}/roster": { "get": { "tags": [ "Admin", "Teams" ], "summary": "List club roster (admin)", "description": "Club admin. `teamId` is a team id or slug. Requires canManageTeam: TeamAdmin owner, editor, or legacy admin on that team, or a platform admin/superadmin. Viewers are 403. Returns active and departed players (rows are never deleted), rosterVerifiedByClubAt (ISO-8601 or null), and the newest 100 audit entries. Player: { id, name, jerseyNumber, position, status, signedAt, departedAt, isActive, rosterProvenance, vendorProvider }. status is signed|tryout|loan|injured|departed or null. Dates are YYYY-MM-DD or null. rosterProvenance \"club\" or vendorProvider \"club\" means vendor sync will not overwrite the row.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { rosterVerifiedByClubAt, players, audit } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } }, "post": { "tags": [ "Admin", "Teams" ], "summary": "Add club roster player", "description": "Same canManageTeam gate as GET. Creates a player with rosterProvenance and vendorProvider \"club\". status departed stores isActive false. Never deletes. 409 when the normalized name already exists on the team.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "jerseyNumber", "position", "status", "signedAt", "departedAt" ], "properties": { "name": { "type": "string" }, "jerseyNumber": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 99 }, "position": { "type": "string", "enum": [ "G", "D", "C", "LW", "RW", "F" ] }, "status": { "type": "string", "enum": [ "signed", "tryout", "loan", "injured", "departed" ] }, "signedAt": { "type": [ "string", "null" ], "description": "YYYY-MM-DD or null" }, "departedAt": { "type": [ "string", "null" ], "description": "YYYY-MM-DD or null" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "{ success, data: { id, isActive, status, signedAt, departedAt } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" }, "409": { "description": "{ success: false, error, code: CONFLICT }" } } } }, "/api/admin/teams/{teamId}/roster/{playerId}": { "patch": { "tags": [ "Admin", "Teams" ], "summary": "Edit club roster player", "description": "Same canManageTeam gate. Replaces name, jersey, position, status, and dates. Sets rosterProvenance to club and keeps an existing vendor id. status departed sets isActive false; any other status sets isActive true. Never deletes the row.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "playerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "jerseyNumber", "position", "status", "signedAt", "departedAt" ], "properties": { "name": { "type": "string" }, "jerseyNumber": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 99 }, "position": { "type": "string", "enum": [ "G", "D", "C", "LW", "RW", "F" ] }, "status": { "type": "string", "enum": [ "signed", "tryout", "loan", "injured", "departed" ] }, "signedAt": { "type": [ "string", "null" ] }, "departedAt": { "type": [ "string", "null" ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { id, isActive, status, signedAt, departedAt } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "Player or team not found" }, "409": { "description": "{ success: false, error, code: CONFLICT }" } } } }, "/api/admin/teams/{teamId}/roster/{playerId}/status": { "patch": { "tags": [ "Admin", "Teams" ], "summary": "Change club roster membership status", "description": "Same canManageTeam gate. Changes status without resending the rest of the player. departed sets isActive false and, when departedAt is omitted and unset, fills departedAt with today (UTC). signed, tryout, loan, and injured set isActive true. Leaving departed clears departedAt unless the body sends one. Date keys are optional; omit a key to leave that date unchanged, or send null to clear it. Sets rosterProvenance to club. Never deletes the row.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "playerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "signed", "tryout", "loan", "injured", "departed" ] }, "signedAt": { "type": [ "string", "null" ], "description": "YYYY-MM-DD. Omit to leave unchanged." }, "departedAt": { "type": [ "string", "null" ], "description": "YYYY-MM-DD. Omit to leave unchanged, except the departed default above." } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { id, isActive, status, signedAt, departedAt } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "Player or team not found" } } } }, "/api/admin/teams/{teamId}/roster/{playerId}/deactivate": { "post": { "tags": [ "Admin", "Teams" ], "summary": "Deactivate club roster player", "description": "Same canManageTeam gate. Shortcut for status departed: isActive false, rosterStatus departed, departedAt today (UTC) when empty, rosterProvenance club. Empty body. The row stays. A vendor provider already on the row is not overwritten.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "playerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { id, isActive: false, status: departed, signedAt, departedAt } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "Player or team not found" } } } }, "/api/admin/teams/{teamId}/roster/audit": { "get": { "tags": [ "Admin", "Teams" ], "summary": "Club roster audit log", "description": "Same canManageTeam gate. Newest 100 changes. Entry: { id, playerId, action, summary, actorName, createdAt, changes }. action is create|update|status|deactivate|import|confirm. playerId is null for confirm. createdAt is ISO-8601. changes is a map of field to { from, to }, or null.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { audit } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/admin/teams/{teamId}/roster/confirm": { "post": { "tags": [ "Admin", "Teams" ], "summary": "Confirm club roster", "description": "Same canManageTeam gate. Sets Team.rosterVerifiedByClubAt and writes an audit row with action confirm. Does not edit players. The public team and roster payloads expose the same timestamp as rosterVerifiedByClubAt. Empty body.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { rosterVerifiedByClubAt } } ISO-8601" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/admin/teams/{teamId}/roster/template": { "get": { "tags": [ "Admin", "Teams" ], "summary": "Club roster CSV template", "description": "Same canManageTeam gate. Default response is text/csv attachment club-roster-template.csv. ?format=json or Accept: application/json returns { success, data: { filename, csv } }. Header: id,name,jerseyNumber,position,status,signedAt,departedAt.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "text/csv file, or { success, data: { filename, csv } } when format=json" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/admin/teams/{teamId}/roster/import/preview": { "post": { "tags": [ "Admin", "Teams" ], "summary": "Preview club roster CSV import", "description": "Same canManageTeam gate. Does not write. Full-import diff: adds, updates (field changes only), deactivations of active players missing from the file, and row errors. A non-empty errors list clears deactivations. Match on id when the cell is non-empty; unknown ids are errors, not creates. Otherwise match on a name folded case-, accent-, and whitespace-insensitively (apostrophes and hyphens stay). Limit 1 MB and 500 data rows.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "csv" ], "properties": { "csv": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { adds, updates, deactivations, errors } }. adds[]: { rowNumber, id, name, jerseyNumber, position, status, signedAt, departedAt }. updates[]: { playerId, name, rowNumber, changes, next }. deactivations[]: { playerId, name }. errors[]: { row, message }." }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/admin/teams/{teamId}/roster/import": { "post": { "tags": [ "Admin", "Teams" ], "summary": "Apply club roster CSV import", "description": "Same canManageTeam gate and the same body as preview. Writes only when errors is empty. Adds and updates set rosterProvenance club. Active players missing from the file are deactivated (isActive false, status departed), never deleted. One transaction; a unique-name collision rolls back and returns 409.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "csv" ], "properties": { "csv": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { added, updated, deactivated } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR } Row errors; nothing written." }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" }, "409": { "description": "{ success: false, error, code: CONFLICT }" } } } }, "/api/admin/teams/{teamId}/season-stats/refresh": { "post": { "tags": [ "Admin", "Teams" ], "summary": "Refresh team player season stats", "description": "Team managers (canManageTeam: platform admin, or the team's owner/editor/legacy admin). Recomputes PlayerSeasonStat rows for one season from every final game of the team in its API-Sports league (regular season and playoffs; friendlies excluded): derives games nobody viewed, links null-playerId stat rows (exact name, else the team's unique initial+surname row), and upserts one row per active roster player and per linked player with stats. Never writes overrides. Idempotent. teamId is an id or slug. 400 when the team has no API-Sports id or no resolvable league (pass leagueVendorId).", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "season": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "leagueVendorId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { teamId, season, leagueVendorId, gamesCounted, derivedGames, relinkedRows, players } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "teamId", "season", "leagueVendorId", "gamesCounted", "derivedGames", "relinkedRows", "players" ], "properties": { "teamId": { "type": "string" }, "season": { "type": "integer" }, "leagueVendorId": { "type": "integer" }, "gamesCounted": { "type": "integer", "minimum": 0 }, "derivedGames": { "type": "integer", "minimum": 0 }, "relinkedRows": { "type": "integer", "minimum": 0 }, "players": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "Team or player not found" } } } }, "/api/admin/teams/{teamId}/roster/{playerId}/season-stats": { "put": { "tags": [ "Admin", "Teams" ], "summary": "Set player season stat override", "description": "Platform admin only. Replaces the player's season override for fields the feed cannot see (gamesPlayed, corrected goals/assists/pim, goalieTier, starTier as Prisma Rarity strings). {} clears it. Stored separately; a refresh never overwrites it. The player must be on the team. teamId is an id or slug.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "playerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "season", "in": "query", "required": false, "description": "Season start year (2026 = 2026-27). Defaults to the current hockey season.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlayerSeasonStatOverride" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: PlayerSeasonStatRow }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PlayerSeasonStatRow" } } } } } }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "Team or player not found" } } } }, "/api/upload/banner": { "post": { "tags": [ "Misc", "Platform and infrastructure" ], "summary": "Upload banner", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Banner URL" } } } }, "/api/user": { "get": { "tags": [ "User" ], "summary": "Get user or suggestions", "description": "suggest=1: suggested users (auth). No id: current user (auth). id and/or handle: public profile. Current-user payload always includes `interests` (array; empty means none) and `interestsCapturedAt` (ISO 8601 or null if never captured). Rep: `trophies` is the PointsHistory sum only and never changes meaning — old clients read it. `fanRep` is the combined total (PointsHistory + RepLedgerEntry) and is what new clients should read. Self payload also includes optional `config` (DSE-368 feed control plane: feedRanking, signalsEnabled, signalSampleRate, adsEnabled, adsPersonalized, experiments). `adsEnabled` is ad inventory (first-party, defaults on); `adsPersonalized` is whether that inventory may be selected from behavioural signals. It is true only when the FEED_ADS_PERSONALIZED kill switch is on AND UserSettings.personalizedAdsConsent is true (GDPR Art. 6(1)(a), default false, #785). When UserSettings.analyticsPersonalization is false (#614), config is forced to legacy / signals off / sample 0, while `adsEnabled` passes through and ad consent is unchanged. Omitted for other profiles / signed-out — clients use safe defaults (legacy / signals off / sample 0 / inventory on / targeting off). Owner config also always emits lineupCtaWindow: { opensBeforeKickoffMs, closesAfterEndMs } | null (#1116). Both values are integers clamped to 0..86400000, from FEED_LINEUP_CTA_OPENS_BEFORE_KICKOFF_MS and FEED_LINEUP_CTA_CLOSES_AFTER_END_MS; missing/incomplete/invalid configuration returns null. Trimmed signed decimal integers are accepted; fractions, exponents, hexadecimal and non-finite values are invalid. No automatic 4h/15m defaults are enabled. Analytics personalization opt-out preserves this global product timing.", "parameters": [ { "name": "suggest", "in": "query", "schema": { "type": "string" } }, { "name": "id", "in": "query", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "User object or suggestions array" }, "401": { "description": "Unauthorized" } } }, "patch": { "tags": [ "User" ], "summary": "Update user", "description": "Body: user fields to update. Writing `interests` stamps `interestsCapturedAt` on first capture.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Updated user" } } } }, "/api/user/check-username": { "get": { "tags": [ "User" ], "summary": "Check handle availability", "description": "Public case-insensitive handle check. Query: username. Returns { available: boolean }.", "parameters": [ { "name": "username", "in": "query", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ available: boolean }" }, "400": { "description": "Username is required" } } } }, "/api/user/all": { "get": { "tags": [ "User" ], "summary": "List community users", "description": "Authenticated directory of onboarded users, newest first. Excludes the caller. Query limit is clamped to 1–100 (default 50). excludeFollowing=true also drops users the caller already follows. Each user includes id, name, handle, profileUrl, profileUrlThumbhash, bio, location, favoriteTeam, favoritePlayer, rivalTeam, and stats { followerCount, totalPoints }. total is the returned count, not the full population. Cache-Control is no-store. Rate limit: 30 requests per minute.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "excludeFollowing", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { users, total } }", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "users", "total" ], "properties": { "users": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "handle", "profileUrl", "profileUrlThumbhash", "bio", "location", "favoriteTeam", "favoritePlayer", "rivalTeam", "stats" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "profileUrl": { "type": "string" }, "profileUrlThumbhash": { "type": [ "string", "null" ] }, "bio": { "type": "string" }, "location": { "type": "string" }, "favoriteTeam": { "type": "string" }, "favoritePlayer": { "type": "string" }, "rivalTeam": { "type": "string" }, "stats": { "type": "object", "required": [ "followerCount", "totalPoints" ], "properties": { "followerCount": { "type": "integer" }, "totalPoints": { "type": "integer" } } } } } }, "total": { "type": "integer" } } } } } } } }, "401": { "description": "Authentication required" }, "429": { "description": "RATE_LIMITED" }, "500": { "description": "FETCH_USERS_ERROR" } } } }, "/api/user/collectibles": { "get": { "tags": [ "User" ], "summary": "Get user collectibles", "description": "Data: { collectibles }. Each item carries walletAddress (the wallet the copy was acquired into; null = pre-#928 legacy row), lockedBy and lockedQuantity. When set, returns only rows acquired into this wallet (case-insensitive). Omit to return every wallet's rows. Each item adds serial: CardSerial | null — the lowest serial among the user's copies of that collectible (ties: earliest mint); null when no copy has a recorded serial. Each item adds player: CardPlayer | null at the top level of the row (next to serial, not inside collectible): the roster player linked to that collectible; null when none is linked.", "parameters": [ { "name": "walletAddress", "in": "query", "required": false, "schema": { "type": "string" }, "description": "When set, returns only rows acquired into this wallet (case-insensitive). Omit to return every wallet's rows." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Collectibles data, including listing/offer lock metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "collectibles": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryLockedCollectible" } } } } } } } } } } } }, "/api/user/completed-quests": { "get": { "tags": [ "User" ], "summary": "Get completed quests", "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ quests }" } } } }, "/api/user/delete": { "delete": { "tags": [ "User" ], "summary": "Delete account", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "Optional password for explicit re-authentication prior to deletion." } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { message } }" }, "401": { "description": "Authentication or re-authentication required" } } } }, "/api/user/delete/dry-run": { "get": { "tags": [ "User" ], "summary": "Dry-run account deletion", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Dry-run summary" } } } }, "/api/user/dev-card-settings": { "get": { "tags": [ "User" ], "summary": "Get dev card settings", "description": "Internal/debug card settings endpoint.", "x-hidden": true, "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, isDev, user, settings }" } } }, "post": { "tags": [ "User" ], "summary": "Update dev card settings", "description": "Internal/debug card settings mutation endpoint.", "x-hidden": true, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success }" } } } }, "/api/user/featured-collectibles": { "get": { "tags": [ "User" ], "summary": "Get featured collectibles for a profile", "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "string" } }, { "name": "handle", "in": "query", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { collectibles } }" }, "401": { "description": "Auth required when neither userId nor handle is provided" }, "404": { "description": "User not found for handle" } } }, "put": { "tags": [ "User" ], "summary": "Replace authenticated user's featured collectibles (max 12)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collectibleIds" ], "properties": { "collectibleIds": { "type": "array", "items": { "type": "string" }, "maxItems": 12 } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { ok: true } }" }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } } } }, "/api/user/follow": { "get": { "tags": [ "User" ], "summary": "Check follow status", "parameters": [ { "name": "targetUserId", "in": "query", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ isFollowing }" } } }, "post": { "tags": [ "User" ], "summary": "Follow user", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "targetUserId" ], "properties": { "targetUserId": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, follow, counts }" } } }, "delete": { "tags": [ "User" ], "summary": "Unfollow user", "parameters": [ { "name": "targetUserId", "in": "query", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, counts }" } } } }, "/api/user/followers": { "get": { "tags": [ "User" ], "summary": "List followers/following", "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ users, total, page, totalPages }" } } } }, "/api/user/isOnboarded": { "get": { "tags": [ "User" ], "summary": "Check onboarded", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "true or false" } } } }, "/api/user/mutes": { "get": { "tags": [ "User" ], "summary": "List muted users", "description": "Authenticated list of users the viewer has muted. One-way hide; the muted user is not notified.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: [{ id, createdAt, user }] }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } }, "post": { "tags": [ "User" ], "summary": "Mute user", "description": "Persist a one-way mute. Body mutedUserId accepts a User.id or display handle (chat messages historically only sent the handle).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mutedUserId": { "type": "string" }, "handle": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "{ success, data: { success, id, muterId, mutedId } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR } — missing/empty mutedUserId or handle, or self-mute" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND } — mutedUserId/handle did not resolve" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } }, "delete": { "tags": [ "User" ], "summary": "Unmute user", "description": "Remove a mute. Query mutedUserId accepts a User.id or handle.", "parameters": [ { "name": "mutedUserId", "in": "query", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { success: true } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR } — missing/empty mutedUserId or handle" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND } — mutedUserId/handle did not resolve" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } } }, "/api/user/blocks": { "get": { "tags": [ "User" ], "summary": "List blocked users", "description": "Authenticated list of users the viewer has blocked. Stronger than mute: blocked users are excluded from social surfaces.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: [{ id, createdAt, user }] }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } }, "post": { "tags": [ "User" ], "summary": "Block user", "description": "Persist a block. Body must include blockedUserId or handle (User.id or display handle; empty strings rejected).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "blockedUserId": { "type": "string", "minLength": 1 }, "handle": { "type": "string", "minLength": 1 } }, "anyOf": [ { "required": [ "blockedUserId" ] }, { "required": [ "handle" ] } ] } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "{ success, data: { id, blockerId, blockedId, createdAt } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR } — missing/empty blockedUserId or handle, or self-block" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND } — blockedUserId/handle did not resolve" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } } }, "delete": { "tags": [ "User" ], "summary": "Unblock user", "description": "Remove a block. Provide blockedUserId as a query param, or send blockedUserId/handle in a JSON body (User.id or display handle).", "parameters": [ { "name": "blockedUserId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "User.id or handle. Optional when the same target is sent in the JSON body." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { success: true } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR } — missing/empty blockedUserId or handle" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND } — blockedUserId/handle did not resolve" }, "500": { "description": "{ success: false, error, code: INTERNAL_ERROR }" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "blockedUserId": { "type": "string", "minLength": 1 }, "handle": { "type": "string", "minLength": 1 } }, "anyOf": [ { "required": [ "blockedUserId" ] }, { "required": [ "handle" ] } ] } } } } } }, "/api/user/onboarding": { "get": { "tags": [ "User" ], "summary": "Get onboarding status", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { isComplete, freePackId } }. `freePackId` is the granted PackPurchase.id of the still-unopened onboarding welcome pack, or null." } } }, "post": { "tags": [ "User" ], "summary": "Complete onboarding", "description": "Optional body `{ interests?: string[] }` is persisted and stamps `interestsCapturedAt` when present. Response data is `{ completed: true, freePackId }` where `freePackId` is the granted PackPurchase.id (open via POST /api/packs/{id}/open) or null if the grant degraded.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { completed, freePackId } } (freePackId is the granted PackPurchase.id, or null if the grant degraded)" } } } }, "/api/user/packs": { "get": { "tags": [ "User" ], "summary": "Get user packs", "description": "Each packs[] item includes lockedBy. Its nested pack includes animationId plus PackGlbMedia. modelUrl falls back to animationId only when the column is null. It also carries the pre-rendered opening the app plays when the live scene can't run: videoUrl, videoDurationMs and whiteFlashMs (each null when the pack has none). cardBackBranding ({ teamName, teamSlug, logoUrl, isDSports } or null) brands the card back the app draws when no card-back art is set. When set, returns only rows acquired into this wallet (case-insensitive). Omit to return every wallet's rows.", "parameters": [ { "name": "walletAddress", "in": "query", "required": false, "schema": { "type": "string" }, "description": "When set, returns only rows acquired into this wallet (case-insensitive). Omit to return every wallet's rows." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ packs } with lock tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "packs": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryLockedPack" } } } } } } } } } } } }, "/api/user/packs/opened": { "get": { "tags": [ "User" ], "summary": "Get opened packs", "description": "Each packs[] item includes lockedBy. When set, returns only rows acquired into this wallet (case-insensitive). Omit to return every wallet's rows.", "parameters": [ { "name": "walletAddress", "in": "query", "required": false, "schema": { "type": "string" }, "description": "When set, returns only rows acquired into this wallet (case-insensitive). Omit to return every wallet's rows." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ packs } with lock tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "packs": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryLockedPack" } } } } } } } } } } } }, "/api/user/privacy": { "get": { "tags": [ "User" ], "summary": "Get privacy setting", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ isPrivate }" } } }, "patch": { "tags": [ "User" ], "summary": "Update privacy", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "isPrivate": { "type": "boolean" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, isPrivate }" } } } }, "/api/user/profile": { "get": { "tags": [ "User" ], "summary": "Get profile", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Profile" } } }, "patch": { "tags": [ "User" ], "summary": "Update profile", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "bannerUrl": { "type": "string" }, "profileUrl": { "type": "string" }, "userTheme": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, user }" } } }, "post": { "tags": [ "User" ], "summary": "Create/onboard profile", "description": "Onboarding payload.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, user, ... }" } } } }, "/api/user/recommended": { "get": { "tags": [ "User" ], "summary": "Recommended users", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ users, total }" } } } }, "/api/user/search": { "get": { "tags": [ "User" ], "summary": "Search users", "description": "Authenticated paginated user search. Default scope matches handle, name, and (for q length >= 2) location. `scope=mention` matches handle and name only and omits users without a handle — use this from @mention typeahead so a city fragment cannot outrank a handle. `limit` is accepted (1–50, default 20). Each row uses `profileUrl` (not `avatar`); there is no `level` field. `handle` is nullable on the default scope and non-empty on `scope=mention`. `location` is always returned as a profile field; only the default scope uses it for matching and ranking.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Page size. Accepted; typeaheads should send their visible row count (e.g. 6) instead of slicing a full page client-side.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "scope", "in": "query", "description": "Omit for the default explore search. `mention` matches handle and name only.", "schema": { "type": "string", "enum": [ "mention" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { users, total, page, totalPages, query } }", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "users", "total", "page", "totalPages", "query" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserSearchUser" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" }, "query": { "type": "string" } } } } } } } }, "400": { "description": "Empty q, invalid page/limit, or unknown scope", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ] } } } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/user/settings": { "get": { "tags": [ "User" ], "summary": "Get user settings", "description": "Authenticated settings row. Creates one from User.isPrivate when missing. privateProfile mirrors isPrivate. Includes per-channel notify* booleans, accessibility flags, liveScoreUpdates (opt-in, default false) for OS live score surfaces, analyticsPersonalization (opt-out, default true) for feed ranking and behavioural signals (#614), personalizedAdsConsent (explicit consent for personalized ads, default false, #785) with personalizedAdsConsentAt (ISO-8601 or null) and personalizedAdsConsentVersion (currently version 1, or null until the fan chooses), and hqTextMode (marquee | expand | wrap, default expand) for HQ long-text display (#702). Includes teamNameDisplayMode (full | name_only, default full) for club-name display: full is city plus name (Montreal Canadiens); name_only is the club name (Canadiens). Includes packOpenMotion (system | full | reduced, default system) for the pack-opening motion preference (#884). Includes packSoundEnabled (boolean, default true) for the pack-opening sounds toggle (#920). Also returns data.appTour.seenPages (#777): { page, completedAt }[] for the session user, oldest completion first, empty when no tour page has been marked seen. completedAt is ISO-8601 UTC and is not refreshed by a repeat mark. Tour writes are POST and DELETE /api/user/settings/app-tour; this PATCH does not accept or return appTour. Includes showPullsInFeed (default true) for the live pull feed opt-in (#883). Includes notifyPacks (boolean, default true) for the free-packs-refilled push opt-out (#914). Includes packAntialias (auto | off | fxaa | smaa | msaa, default auto) for the pack-opening antialiasing mode (#923). Includes packQuality (auto | low | mid | high, default auto; native #854/W8); the server stores the choice and the device resolves auto. Includes packSummaryLayout (auto | grid | compact | carousel | marquee, default auto; #1155) for the 3D pack-opening summary layout; the server stores the choice and native renders it. Includes customizerPreviewMode (full | compact, default full) for the pinned customizer preview (#931). Includes showOpenChoiceSheet (boolean, default true) and defaultOpenAction (open_now | open_later, default open_later; stored as PackOpenAction OPEN_NOW | OPEN_LATER) plus packOpenChoice { showSheet, defaultAction } for the post-checkout Open now / Open later sheet (#930). The server never opens a pack from this preference. Includes timezone (IANA, or null until the device reports it), quietStart, and quietEnd (HH:mm 24h, or null) for quiet hours (#947). A missing zone, a half-set window, or equal start and end does not suppress pushes. Includes marketingEmailOptIn (CASL express consent for marketing email, default false, #1032) with marketingEmailConsentAt (ISO-8601 or null) and marketingEmailConsentSource (settings | onboarding, or null); both are null unless the fan is opted in.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data } where data is the UserSettings row plus appTour: { seenPages: [{ page, completedAt }] }. seenPages is [] when nothing has been marked. Also packOpenChoice { showSheet, defaultAction }, showOpenChoiceSheet, defaultOpenAction (open_now | open_later), customizerPreviewMode (full | compact), and packAntialias (auto | off | fxaa | smaa | msaa), plus packQuality (auto | low | mid | high; default auto; device resolves auto), and packSummaryLayout (auto | grid | compact | carousel | marquee; default auto). Also autoRefreshIntervalSec (0 or 30..3600 seconds, default 60), requirePinForInventoryMove (boolean, default false), walletReminderSnoozedUntil, and walletReminderDismissedAt (ISO-8601 date-times with timezone or null)." }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "404": { "description": "{ success: false, error: User not found, code: NOT_FOUND }" } } }, "patch": { "tags": [ "User" ], "summary": "Update user settings", "description": "Boolean fields only plus appearanceTheme, hqTextMode (marquee | expand | wrap, default expand; unknown values 400), teamNameDisplayMode (full | name_only, default full), and packOpenMotion (system | full | reduced, default system; unknown values 400). packSoundEnabled (#920) is a boolean like the other toggles (default true on a new row; a non-boolean is ignored). Unknown teamNameDisplayMode values, including null and empty string, return 400 VALIDATION_ERROR. Omitting teamNameDisplayMode or packOpenMotion leaves the stored value unchanged. Unknown packOpenMotion values, including null and empty string, return 400 VALIDATION_ERROR. A new settings row defaults to full. full is city plus name (Montreal Canadiens); name_only is the club name (Canadiens). Persist notifyTeams, notifyMilestones, notifyCommunity, liveScoreUpdates (opt-in Live Activity / ongoing notification consent), analyticsPersonalization (opt-out; default true), and personalizedAdsConsent (boolean, default false) separately. The server stamps personalizedAdsConsentAt and personalizedAdsConsentVersion (currently version 1) when the choice changes, on the first explicit choice, or when re-granting against a new version. Clients cannot set the timestamp or version; a client-supplied value is ignored. The settings row commits before impression cleanup. A privateProfile change writes User.isPrivate in that same transaction, so a cleanup failure cannot leave the settings row private while the user row stays public. Sending personalizedAdsConsent false (including a retry) or analyticsPersonalization false folds that user's backfill AdImpression rows into AdImpressionDailyRollup one page per transaction, then deletes the raw rows. FeedSignal is deleted only when analyticsPersonalization is set to false, and that purge stays in the settings transaction. A cleanup that stops early returns 500 while the saved flag stays; sending the same false again continues the delete. Do not write preferences.privacy. Does not read or write app tour progress; the response is the settings row without appTour. Includes showPullsInFeed (default true) for the live pull feed opt-in (#883). notifyPacks (#914) is a boolean like the other toggles (default true on a new row; a non-boolean is ignored). packAntialias (#923) is auto | off | fxaa | smaa | msaa (default auto); trim and lowercase; unknown values including null and empty string return 400 VALIDATION_ERROR and write nothing. packQuality (#854/W8) is auto | low | mid | high (default auto); the server stores the choice and the device resolves auto; invalid values return 400 VALIDATION_ERROR and write nothing. packSummaryLayout (#1155) is auto | grid | compact | carousel | marquee (default auto); trim and lowercase; the server stores the choice and native renders it; invalid values, including null and empty string, return 400 VALIDATION_ERROR and write nothing. customizerPreviewMode (#931) is full | compact (default full) with the same normalization and 400. showOpenChoiceSheet (#930) must be a boolean when present (non-booleans, including null, return 400 VALIDATION_ERROR). defaultOpenAction (#930) is exactly open_now | open_later (case-checked; OPEN_NOW, blanks, and null return 400 VALIDATION_ERROR). The stored enum is OPEN_NOW | OPEN_LATER and the response speaks open_now | open_later, with packOpenChoice { showSheet, defaultAction }. Omitting one of these fields leaves it unchanged. A new row defaults packAntialias to auto, customizerPreviewMode to full, showOpenChoiceSheet to true, and defaultOpenAction to open_later. Checkout and pack open ignore the preference. timezone, quietStart, and quietEnd (#947) follow the other fields: omitted leaves the stored value unchanged, null clears it, and a valid IANA zone or HH:mm is stored. Invalid timezone returns 400 VALIDATION_ERROR (Invalid timezone. Expected an IANA zone such as America/Toronto.). Invalid quietStart or quietEnd returns 400 (Invalid quiet hours. Expected HH:mm (24h) or null.). Nothing is written on 400. A usable window suppresses goal and kickoff pushes and delivers final scores silently. marketingEmailOptIn (#1032) must be a boolean when present; any other value returns 400 VALIDATION_ERROR. Optional marketingEmailConsentSource is settings | onboarding (default settings); unknown values return 400 VALIDATION_ERROR. On opt-in the server stamps marketingEmailConsentAt and marketingEmailConsentSource; a repeated opt-in keeps the original stamp. On opt-out both are cleared to null. Clients cannot set marketingEmailConsentAt; a client-supplied value is ignored. Each change (off to on, on to off) appends a MarketingEmailConsentEvent row (optIn, source, createdAt) in the same transaction.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Partial settings write. A JSON object is required; an omitted body is not valid JSON and the handler returns 500. Every settings field inside the object stays optional. teamNameDisplayMode is the closed enum. packAntialias, packQuality, packSummaryLayout, customizerPreviewMode, and defaultOpenAction are closed strings. showOpenChoiceSheet is a strict boolean. autoRefreshIntervalSec is an integer (0 or 30..3600 seconds).", "additionalProperties": true, "properties": { "teamNameDisplayMode": { "$ref": "#/components/schemas/TeamNameDisplayMode" }, "packAntialias": { "$ref": "#/components/schemas/PackAntialias" }, "packQuality": { "$ref": "#/components/schemas/PackQuality" }, "packSummaryLayout": { "$ref": "#/components/schemas/PackSummaryLayout" }, "customizerPreviewMode": { "$ref": "#/components/schemas/CustomizerPreviewMode" }, "showOpenChoiceSheet": { "type": "boolean", "description": "When true, the fan sees the Open now / Open later sheet after checkout (#930). Default true.", "default": true }, "defaultOpenAction": { "$ref": "#/components/schemas/PackOpenAction" }, "timezone": { "type": "string", "nullable": true, "description": "IANA zone such as America/Toronto (#947). Null clears. Omitted leaves the stored value unchanged.", "example": "America/Toronto" }, "quietStart": { "type": "string", "nullable": true, "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Quiet-hours start, HH:mm 24h, inclusive, in timezone (#947). Null clears.", "example": "22:00" }, "quietEnd": { "type": "string", "nullable": true, "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Quiet-hours end, HH:mm 24h, exclusive, in timezone (#947). start greater than end wraps midnight. Null clears.", "example": "07:00" }, "requirePinForInventoryMove": { "type": "boolean", "default": false, "description": "Require the wallet PIN before moving inventory between wallets." }, "walletReminderSnoozedUntil": { "type": "string", "format": "date-time", "nullable": true, "description": "Snooze the create-a-wallet reminder until an ISO-8601 date-time with timezone. Null clears; valid timestamps may be at most 30 days ahead, and past timestamps are accepted." }, "walletReminderDismissedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO-8601 date-time with timezone when the fan dismissed the create-a-wallet reminder. Null clears." }, "autoRefreshIntervalSec": { "oneOf": [ { "type": "integer", "enum": [ 0 ] }, { "type": "integer", "minimum": 30, "maximum": 3600 } ], "description": "Foreground auto-refresh cadence in seconds (engage-native). 0 disables periodic refresh (pull-to-refresh still works); otherwise 30..3600. Server default 60.", "default": 60, "example": 120 }, "marketingEmailOptIn": { "type": "boolean", "description": "Marketing email consent (#1032). Non-booleans return 400 VALIDATION_ERROR." }, "marketingEmailConsentSource": { "type": "string", "enum": [ "settings", "onboarding" ], "description": "Where the fan opted in; defaults to settings. Used only with marketingEmailOptIn true. Unknown values return 400 VALIDATION_ERROR." } } } } } }, "responses": { "200": { "description": "{ success, data } where data is the UserSettings row, including teamNameDisplayMode (full | name_only). Also packAntialias, packQuality, packSummaryLayout, customizerPreviewMode, showOpenChoiceSheet, defaultOpenAction (open_now | open_later), and packOpenChoice { showSheet, defaultAction }. Also autoRefreshIntervalSec (0 or 30..3600 seconds, default 60), requirePinForInventoryMove (boolean, default false), walletReminderSnoozedUntil, and walletReminderDismissedAt (ISO-8601 date-times with timezone or null)." }, "400": { "description": "{ success: false, error: Invalid teamNameDisplayMode. Expected full | name_only., code: VALIDATION_ERROR }. Also returned for an invalid hqTextMode. Nothing is written. Also returned for an invalid packAntialias (Invalid packAntialias. Expected auto | off | fxaa | smaa | msaa.), customizerPreviewMode (Invalid customizerPreviewMode. Expected full | compact.), showOpenChoiceSheet (Invalid showOpenChoiceSheet. Expected boolean.), or defaultOpenAction (Invalid defaultOpenAction. Expected open_now | open_later.), or packQuality (Invalid packQuality. Expected auto | low | mid | high.). Also returned for an invalid packSummaryLayout (Invalid packSummaryLayout. Expected auto | grid | compact | carousel | marquee.). Also returned for an invalid timezone (Invalid timezone. Expected an IANA zone such as America/Toronto.) or quiet hours (Invalid quiet hours. Expected HH:mm (24h) or null.). Nothing is written. Also returned for an invalid autoRefreshIntervalSec (Invalid autoRefreshIntervalSec. Expected 0 or an integer 30..3600 (seconds).). Nothing is written." }, "500": { "description": "{ success: false, error: Failed to update settings, code: INTERNAL_ERROR }. Impression cleanup that stops early uses this response. The settings row, including privateProfile mirrored onto User.isPrivate, is already saved. Sending the same false again continues the delete." } } } }, "/api/user/settings/app-tour": { "post": { "tags": [ "User" ], "operationId": "markAppTourPageSeen", "summary": "Mark an app tour page seen", "description": "Authenticated. Marks one tour page seen for the session user (#777). Idempotent: a repeat call, including one that loses a unique-constraint race with another device, returns 200 with alreadySeen true and the original completedAt. It does not insert a duplicate row and it is not an error. A userId in the body is ignored. Page key format: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, length 1-64 (lowercase kebab-case). Canonical auto-start keys (engage-native TOP_LEVEL_PAGES): locker-room, leaderboard, profile, shop, wallet. Other TOUR_PAGES keys today: hq-hub, hq-match, post, scan-qr, search, notifications, lb-team, lb-browse, settings, market-packs, market-collectibles, market-trading, market-wishlist. The server accepts any key matching the pattern; it is not a closed enum. completedAt is ISO-8601 UTC.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "page" ], "properties": { "page": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$", "description": "Tour page key. Lowercase kebab-case, 1-64 characters." } } } } } }, "responses": { "200": { "description": "{ success: true, data: { page, completedAt, alreadySeen, appTour: { seenPages: [{ page, completedAt }] } } }. alreadySeen is false on the inserting call and true when the row already existed. completedAt does not move. seenPages is the full set, oldest completion first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "page", "completedAt", "alreadySeen", "appTour" ], "properties": { "page": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "alreadySeen": { "type": "boolean" }, "appTour": { "type": "object", "required": [ "seenPages" ], "properties": { "seenPages": { "type": "array", "items": { "type": "object", "required": [ "page", "completedAt" ], "properties": { "page": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" } } } } } } } } } } } } }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }. Bad or missing page, non-object body, or invalid JSON." }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "404": { "description": "{ success: false, error: User not found, code: NOT_FOUND }. No row is written." } } }, "delete": { "tags": [ "User" ], "operationId": "resetAppTourProgress", "summary": "Reset app tour progress", "description": "Authenticated. Deletes every UserAppTourProgress row for the session user (Replay tour, #777). No body. Idempotent: a second call deletes nothing and still returns 200 with appTour.seenPages empty. Does not affect any other user.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success: true, data: { appTour: { seenPages: [] } } }. seenPages is empty unless a concurrent mark commits after this delete." }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "404": { "description": "{ success: false, error: User not found, code: NOT_FOUND }. Nothing is deleted." } } } }, "/api/user/star-status": { "get": { "tags": [ "User" ], "summary": "Get star status", "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Star status" } } } }, "/api/user/sync-clerk": { "get": { "tags": [ "User" ], "summary": "Sync Clerk user", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, user }" } } } }, "/api/user/team-alerts": { "get": { "tags": [ "User", "Notifications" ], "summary": "List per-team match alert preferences", "description": "One entry per followed team for the authenticated user. Archived teams are omitted. A missing TeamAlertPreference row is returned as the defaults (kickoff, goals, and final on; periodEnd, lineups, and reminder off). Favorites that are not follows are not listed and cannot be customized. notifyTeams=false still suppresses the push.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success: true, data: { teams: Array<{ teamId, kickoff, goals, periodEnd, final, lineups, reminder }> } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" } } } }, "/api/user/team-alerts/{teamId}": { "put": { "tags": [ "User", "Notifications" ], "summary": "Update per-team match alert preferences", "description": "Partial boolean body for kickoff, goals, periodEnd, final, lineups, and reminder. Unknown keys are ignored. Returns the full flag row. 404 when the user does not follow the team, including archived clubs. A missing row is created with schema defaults for omitted flags.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kickoff": { "type": "boolean" }, "goals": { "type": "boolean" }, "periodEnd": { "type": "boolean" }, "final": { "type": "boolean" }, "lineups": { "type": "boolean" }, "reminder": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "{ success: true, data: { teamId, kickoff, goals, periodEnd, final, lineups, reminder } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/user/teams": { "get": { "tags": [ "User", "Teams" ], "summary": "List joined and followed team IDs", "description": "Returns { joinedTeamIds, followedTeamIds } for the authenticated user. joinedTeamIds are club boards only (Leaderboard.isGlobal:false) — D-Sports is never included.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/user/toggle-star": { "post": { "tags": [ "User" ], "summary": "Toggle star", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "starReceiverId": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Toggle result" } } } }, "/api/user/top-users": { "get": { "tags": [ "User" ], "summary": "Top users", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/user/verify-password": { "post": { "tags": [ "User" ], "summary": "Verify password", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success }" } } } }, "/api/v1/cards/{id}/provenance": { "get": { "tags": [ "Cards", "Marketplace" ], "summary": "Card provenance chain", "description": "Public ownership, sale, and mint history assembled from UserCollectible, MarketSale, and MintedNFT. No dedicated card_provenance table.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success: true, data: { card, currentOwners[], transfers[], mints[] } }" }, "400": { "description": "{ success: false, error, code: VALIDATION_ERROR }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/v1/engage/games/catalog": { "get": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Engage game catalog with playability marks", "description": "Additive to GET /api/games/catalog. Query teamId or teamSlug; omit both for the platform catalogue. Marks unplayable rows with playable/reason instead of omitting them. Optional X-Client-Version drives UPDATE_REQUIRED.", "security": [], "parameters": [ { "name": "teamId", "in": "query", "schema": { "type": "string" } }, { "name": "teamSlug", "in": "query", "schema": { "type": "string" } }, { "name": "X-Client-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Native client semver. Games below minClientVersion are marked playable=false, reason=UPDATE_REQUIRED." } ], "responses": { "200": { "description": "{ daily, weekly } EngineCatalogGame[] with playable and reason (UPDATE_REQUIRED | NOT_SHIPPED | null)" }, "404": { "description": "Team not found" } } } }, "/api/v1/engage/games/today": { "get": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Today's catalog with the caller's played-today state", "description": "Same rows as /api/v1/engage/games/catalog plus per-game daily-slot state for the caller: todayStatus UNPLAYED | IN_PROGRESS | PLAYED, sessionId/sessionStatus/attemptsUsed/attemptsRemaining (null without a session), and top-level dayKey/resetsAt (next UTC midnight). locker-singularity derives PLAYED from IdleLedger.lastSeenAt — it has no engine session.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "teamId", "in": "query", "schema": { "type": "string" } }, { "name": "teamSlug", "in": "query", "schema": { "type": "string" } }, { "name": "X-Client-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Native client semver. Games below minClientVersion are marked playable=false, reason=UPDATE_REQUIRED." } ], "responses": { "200": { "description": "{ dayKey, resetsAt, daily, weekly } EngineTodayGame[] with todayStatus + session fields" }, "401": { "description": "Authentication required" }, "404": { "description": "Team not found" }, "500": { "description": "Internal error" } } } }, "/api/v1/engage/games/{gameKey}/session": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Start or resume a daily game session", "description": "Starts or resumes the caller's daily slot for gameKey. Optional X-Client-Version is checked against minClientVersion. prize-wheel-spin and guess-the-player bind teamId/leaderboardId at start (not swappable mid-session). A terminal guess-the-player slot returns 409 GAME_ALREADY_PLAYED. Fixture-linked daily-pickem scenarios add optional internal gameId, leagueId, locksAt, home/away, and option teamId/playerId references (PickemScenario). Private answers remain absent until resolved.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "gameKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Client-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Native client semver. Below minClientVersion returns 403 GAME_UPDATE_REQUIRED." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "type": "string" }, "leaderboardId": { "type": "integer" } } } } } }, "responses": { "200": { "description": "{ session }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "GAME_UPDATE_REQUIRED" }, "404": { "description": "GAME_UNKNOWN" }, "409": { "description": "GAME_DAILY_NOT_ELIGIBLE, GAME_ALREADY_PLAYED" } } } }, "/api/v1/engage/games/{gameKey}/session/{sessionId}/action": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Submit a server-authoritative game action", "description": "Applies input to the session. Outcome is computed on the server. prize-wheel-spin accepts { type: \"spin\" } only; the client never chooses the segment. A sixth daily spin returns 409 GAME_ATTEMPTS_EXHAUSTED. guess-the-player accepts { playerId: string }; the answer is server-held and never returned in the first session scenario. A sixth guess returns 409 GAME_ATTEMPTS_EXHAUSTED. Terminal sessions return 409 GAME_ALREADY_PLAYED on restart. Fresh fixture-linked daily-pickem actions must precede the authoritative fixture start and require an upcoming fixture; late actions return 409 LEG_LOCKED even when the session was opened earlier. Accepted action retries replay their recorded result.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "gameKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "input": { "anyOf": [ { "$ref": "#/components/schemas/PrizeWheelSpinActionInput" }, { "$ref": "#/components/schemas/GuessThePlayerActionInput" }, { "type": "object" } ] }, "sequenceNumber": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "{ outcome, session }", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "anyOf": [ { "$ref": "#/components/schemas/PrizeWheelSpinActionOutcome" }, { "$ref": "#/components/schemas/GuessThePlayerActionOutcome" }, { "type": "object" } ] }, "session": { "type": "object" } } } } } }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT, GAME_ATTEMPTS_EXHAUSTED, LEG_LOCKED" } } } }, "/api/v1/engage/games/{gameKey}/session/{sessionId}/complete": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Complete a game session and bank awards", "description": "Banks awarded points / Rep for the session.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "gameKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ awarded, requested, totalPoints, status }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/v1/engage/games/{gameKey}/session/{sessionId}/forfeit": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Forfeit a game session", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "gameKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ sessionId, status: FORFEITED }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/v1/engage/games/locker-singularity/ledger": { "get": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Read the caller's locker-singularity idle ledger", "description": "First-ever read creates the ledger row. Otherwise credits offline accrual from the server lastSeenAt only (8h cap at 50% efficiency; client timestamps are never accepted) and returns { ledger, accruedBuzz, cappedHours, lastSeenAt }. Toy currencies only: zero writes to DSC balances, Rep, PointsHistory, pack inventory, or marketplace state (d-sports-api#682). The locker-singularity Game row ships as LIVE: the catalog marks it playable=true. Ledger routes serve COMING_SOON rows normally; an absent Game row returns 404 GAME_UNKNOWN with the ledger untouched. Optional X-Client-Version is checked against minClientVersion; below-minimum returns 403 GAME_UPDATE_REQUIRED. Native mirror: locker-singularity spec on the native soft-idle-mini-game branch.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Client-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Native client semver. Below minClientVersion returns 403 GAME_UPDATE_REQUIRED." } ], "responses": { "200": { "description": "{ ledger, accruedBuzz, cappedHours, lastSeenAt }", "content": { "application/json": { "schema": { "type": "object", "required": [ "ledger", "accruedBuzz", "cappedHours", "lastSeenAt" ], "properties": { "ledger": { "$ref": "#/components/schemas/LedgerState" }, "accruedBuzz": { "type": "string", "description": "BigInt serialized as decimal string." }, "cappedHours": { "type": "number" }, "lastSeenAt": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "GAME_UPDATE_REQUIRED" }, "404": { "description": "GAME_UNKNOWN" } } } }, "/api/v1/engage/games/locker-singularity/ledger/taps": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Submit batched buzz taps", "description": "The client sends intent, never values. tapCount is an integer >= 1 with no wire max; values above 100 are clamped server-side (acceptedTaps=100, clampedTaps=tapCount-100). Non-integer or non-positive counts return 400 VALIDATION_ERROR. Sustained abuse returns 429 IDLE_TAP_RATE_LIMITED with a Retry-After header. Mutations carry a UUID v4 idempotencyKey: replaying the same key returns the stored response verbatim, while the same key with a mutated body returns 400 VALIDATION_ERROR with no second credit. Optional X-Client-Version below minClientVersion returns 403 GAME_UPDATE_REQUIRED.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Client-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Native client semver. Below minClientVersion returns 403 GAME_UPDATE_REQUIRED." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tapCount", "idempotencyKey" ], "properties": { "tapCount": { "type": "integer", "minimum": 1, "description": "No wire max; clamped to 100 per call server-side." }, "idempotencyKey": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{ ledger, acceptedTaps, clampedTaps, tapValue }", "content": { "application/json": { "schema": { "type": "object", "required": [ "ledger", "acceptedTaps", "clampedTaps", "tapValue" ], "properties": { "ledger": { "$ref": "#/components/schemas/LedgerState" }, "acceptedTaps": { "type": "integer" }, "clampedTaps": { "type": "integer" }, "tapValue": { "type": "string", "description": "BigInt serialized as decimal string." } } } } } }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "GAME_UPDATE_REQUIRED" }, "404": { "description": "GAME_UNKNOWN" }, "429": { "description": "IDLE_TAP_RATE_LIMITED with Retry-After header" } } } }, "/api/v1/engage/games/locker-singularity/ledger/buy": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Buy generator units with buzz", "description": "quantity is an integer 1-100, else 400 IDLE_MAX_PER_CALL. Unknown generatorId returns 400 VALIDATION_ERROR. Locked generators (unlock thresholds unmet) return 409 IDLE_GENERATOR_LOCKED. Insufficient buzz returns 409 IDLE_INSUFFICIENT_BUZZ with no partial write. Crossing 25/50 owned per generator appends milestones and grants +1 Playbook each (max 8 per run). Idempotent per idempotencyKey. Optional X-Client-Version below minClientVersion returns 403 GAME_UPDATE_REQUIRED.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Client-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Native client semver. Below minClientVersion returns 403 GAME_UPDATE_REQUIRED." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "generatorId", "quantity", "idempotencyKey" ], "properties": { "generatorId": { "type": "string", "enum": [ "rookie-card", "foam-finger-stand", "zamboni-fleet", "banner-press" ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "idempotencyKey": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{ ledger, costPaid, playbooksGranted }", "content": { "application/json": { "schema": { "type": "object", "required": [ "ledger", "costPaid", "playbooksGranted" ], "properties": { "ledger": { "$ref": "#/components/schemas/LedgerState" }, "costPaid": { "type": "string", "description": "BigInt serialized as decimal string." }, "playbooksGranted": { "type": "integer", "description": "0 when no milestone threshold was crossed." } } } } } }, "400": { "description": "VALIDATION_ERROR, IDLE_MAX_PER_CALL" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "GAME_UPDATE_REQUIRED" }, "404": { "description": "GAME_UNKNOWN" }, "409": { "description": "IDLE_GENERATOR_LOCKED, IDLE_INSUFFICIENT_BUZZ" } } } }, "/api/v1/engage/games/locker-singularity/ledger/prestige": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Prestige the ledger for rings", "description": "Requires lifetimeBuzz >= 1,000,000, else 409 IDLE_PRESTIGE_NOT_ELIGIBLE with no state change. Grants marginal rings: max(0, floor(sqrt(cumulativeBuzz / 1e6)) - totalRingsGranted), so repeat prestiges with no new buzz grant 0. Resets buzz, lifetimeBuzz, generators, milestones, playbooks, and upgrades; rings, totalRings, multiplier, and prestigeCount persist. Idempotent per idempotencyKey. Optional X-Client-Version below minClientVersion returns 403 GAME_UPDATE_REQUIRED.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Client-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Native client semver. Below minClientVersion returns 403 GAME_UPDATE_REQUIRED." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "idempotencyKey" ], "properties": { "idempotencyKey": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{ ledger, ringsGranted }", "content": { "application/json": { "schema": { "type": "object", "required": [ "ledger", "ringsGranted" ], "properties": { "ledger": { "$ref": "#/components/schemas/LedgerState" }, "ringsGranted": { "type": "integer" } } } } } }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "GAME_UPDATE_REQUIRED" }, "404": { "description": "GAME_UNKNOWN" }, "409": { "description": "IDLE_PRESTIGE_NOT_ELIGIBLE" } } } }, "/api/v1/engage/games/locker-singularity/ledger/upgrades": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Buy a playbook upgrade node", "description": "Unknown nodeId returns 400 VALIDATION_ERROR. Already-owned nodes return 400 VALIDATION_ERROR (stale client state; never the already-played screen). Insufficient Playbooks returns 409 IDLE_INSUFFICIENT_BUZZ. Costs 1-3 Playbooks per the frozen node table. Idempotent per idempotencyKey. Optional X-Client-Version below minClientVersion returns 403 GAME_UPDATE_REQUIRED.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "X-Client-Version", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Native client semver. Below minClientVersion returns 403 GAME_UPDATE_REQUIRED." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "nodeId", "idempotencyKey" ], "properties": { "nodeId": { "type": "string", "enum": [ "locker-room-10", "packs-25", "hockey-dailies-10", "micd-up-25", "locker-room-global-5", "micd-up-global-5" ] }, "idempotencyKey": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{ ledger }", "content": { "application/json": { "schema": { "type": "object", "required": [ "ledger" ], "properties": { "ledger": { "$ref": "#/components/schemas/LedgerState" } } } } } }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "GAME_UPDATE_REQUIRED" }, "404": { "description": "GAME_UNKNOWN" }, "409": { "description": "IDLE_INSUFFICIENT_BUZZ" } } } }, "/api/v1/engage/games/locker-singularity/ledger/boosts/claim": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Claim a DSC boost (disabled in v1)", "description": "Disabled in v1: the shape is validated, then the route always answers 410 BOOST_DISABLED without touching the ledger (no Game row load, no version gate, no service call). The frozen response shape is reserved for v2 boost rails.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paymentId", "idempotencyKey" ], "properties": { "paymentId": { "type": "string" }, "idempotencyKey": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "410": { "description": "BOOST_DISABLED. Boosts are disabled in v1." } } } }, "/api/v1/engage/rep/breakdown": { "get": { "tags": [ "Rep", "Engage" ], "summary": "Fan Rep totals split by source", "description": "Sums Fan, Club, Player, and Direct ledger rows plus the user's PointsHistory total (questsAndGamesRep). clubRepByTeam only includes Club targetIds that resolve to a Team.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ totalFanRep, fanAmpRep, dsportsDirectRep, clubRep, playerAmpRep, questsAndGamesRep, clubRepByTeam[] }" }, "401": { "description": "Authentication required" } } } }, "/api/v1/engage/rep/ledger": { "get": { "tags": [ "Rep", "Engage" ], "summary": "Paginated Rep ledger history", "description": "Keyset pagination on createdAt DESC, id DESC. Sources: fanAmp, club, playerAmp, dsportsDirect.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "{ entries: { id, source, amount, timestamp, reason }[], nextCursor? }" }, "400": { "description": "Invalid cursor or limit" }, "401": { "description": "Authentication required" } } } }, "/api/v1/kyc/link-token": { "post": { "tags": [ "KYC", "User" ], "summary": "Create a KYC Link token", "description": "Authenticated session helper. Returns a short-lived Link token. No Plaid dashboard URLs or webhook secrets.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "retry": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "{ success, data: { linkToken, expiration, identityVerificationId, status } }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "No prior verification session to retry" } } } }, "/api/v1/kyc/session/complete": { "post": { "tags": [ "KYC", "User" ], "summary": "Complete a KYC Link session", "description": "Accepts the local IdentityVerification id from link-token / kyc-status, or Plaid's identity_verification_id from Link onSuccess.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "identityVerificationId" ], "properties": { "identityVerificationId": { "type": "string" }, "linkSessionId": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ success, data: { status, verifiedAt } }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "502": { "description": "UPSTREAM_ERROR" } } } }, "/api/v1/marketplace": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "List marketplace listings", "description": "Optional auth. Same handler as GET /api/v1/marketplace/listings. Viewer context personalizes serialized rows when a session is present.", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "itemType", "in": "query", "schema": { "type": "string", "enum": [ "card", "pack" ] } }, { "name": "listingType", "in": "query", "schema": { "type": "string", "enum": [ "sale", "auction", "trade", "all" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "recent", "price-asc", "price-desc", "ending-soon", "most-bids" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "minPrice", "in": "query", "schema": { "type": "number" } }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" } }, { "name": "rarities", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated rarities" }, { "name": "teams", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated team ids" }, { "name": "leagues", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated league ids" }, { "name": "sport", "in": "query", "schema": { "type": "string" } }, { "name": "league", "in": "query", "schema": { "type": "string" } }, { "name": "team", "in": "query", "schema": { "type": "string" } }, { "name": "auctionState", "in": "query", "schema": { "type": "string", "enum": [ "all", "ending-soon", "just-started", "has-bids" ] } }, { "name": "includeDemo", "in": "query", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "{ success, data: { listings, totalCount, hasMore } }" }, "400": { "description": "VALIDATION_ERROR" } } } }, "/api/v1/marketplace/activity": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Marketplace activity inbox", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { activity } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/activity/{id}/read": { "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Mark marketplace activity as read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/marketplace/bids/{bidId}": { "delete": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Retract a bid", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bidId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/v1/marketplace/cart": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Get shop cart", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { items } } — pack-type product rows carry packId (the Pack id from metadata, null for legacy mirrors)." }, "401": { "description": "UNAUTHORIZED" } } }, "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Add a shop catalog item to the cart", "description": "Accepts a Product id, Product slug, or Pack id from GET /api/products. Pack ids are resolved to the mirrored Product row (cart FK is Product).", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productId" ], "properties": { "productId": { "type": "string" } } } } } }, "responses": { "201": { "description": "{ success, data }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" } } }, "delete": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Clear the shop cart", "description": "Deletes every ShopCartItem for the authenticated user. DELETE /api/v1/marketplace/cart/{itemId} still removes one line. Does not refund purchases or touch another user's cart.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { removed } } — removed is the number of cart lines deleted." }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/cart/{itemId}": { "patch": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Update cart item quantity", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "integer" } } } } } }, "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } }, "delete": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Remove a cart item", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/marketplace/collectibles/{id}/listings": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Listings for a collectible", "description": "Optional auth. Keyset pagination.", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "{ success, data: { listings, nextCursor? } }" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/marketplace/favorites": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Get shop favorites", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { items } }" }, "401": { "description": "UNAUTHORIZED" } } }, "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Add a product to favorites", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productId" ], "properties": { "productId": { "type": "string" } } } } } }, "responses": { "201": { "description": "{ success, data }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/favorites/{itemId}": { "delete": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Remove a favorite", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/marketplace/featured": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Featured marketplace listings", "description": "Public merchandising feed. Cache-Control: public, s-maxage=60, stale-while-revalidate=30. POST is staff-only and omitted from this public spec.", "security": [], "parameters": [ { "name": "itemType", "in": "query", "schema": { "type": "string", "enum": [ "card", "pack" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 12 } } ], "responses": { "200": { "description": "{ success, data: { listings } }" }, "400": { "description": "VALIDATION_ERROR" } } } }, "/api/v1/marketplace/listings": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "List marketplace listings", "description": "Same list handler as GET /api/v1/marketplace.", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "itemType", "in": "query", "schema": { "type": "string", "enum": [ "card", "pack" ] } }, { "name": "listingType", "in": "query", "schema": { "type": "string", "enum": [ "sale", "auction", "trade", "all" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "recent", "price-asc", "price-desc", "ending-soon", "most-bids" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "minPrice", "in": "query", "schema": { "type": "number" } }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" } }, { "name": "rarities", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated rarities" }, { "name": "teams", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated team ids" }, { "name": "leagues", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated league ids" }, { "name": "sport", "in": "query", "schema": { "type": "string" } }, { "name": "league", "in": "query", "schema": { "type": "string" } }, { "name": "team", "in": "query", "schema": { "type": "string" } }, { "name": "auctionState", "in": "query", "schema": { "type": "string", "enum": [ "all", "ending-soon", "just-started", "has-bids" ] } }, { "name": "includeDemo", "in": "query", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "{ success, data: { listings, totalCount, hasMore } }" }, "400": { "description": "VALIDATION_ERROR" } } }, "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Create a listing", "description": "Requires a valid x-listing-pin-token for the caller. Optional reservePrice on auctions only.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "x-listing-pin-token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "PIN verification token. Missing or invalid → 401 PIN_TOKEN_INVALID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "itemType", "itemId", "type" ], "properties": { "itemType": { "type": "string", "enum": [ "card", "pack" ] }, "itemId": { "type": "string" }, "type": { "type": "string", "enum": [ "sale", "auction", "trade" ] }, "salePrice": { "type": "number" }, "openToTradeOffers": { "type": "boolean" }, "startingBid": { "type": "number" }, "askingPrice": { "type": "number" }, "buyNowPrice": { "type": "number" }, "durationDays": { "type": "integer", "enum": [ 1, 3, 7, 14 ] }, "reservePrice": { "type": "integer", "minimum": 1 }, "tradeCriteria": { "type": "object" } } } } } }, "responses": { "201": { "description": "{ success, data: { listing } }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED or PIN_TOKEN_INVALID" }, "409": { "description": "PACK_NOT_LISTABLE | PACK_ALREADY_OPENED | already listed" }, "503": { "description": "CONFIGURATION_ERROR" } } } }, "/api/v1/marketplace/listings/mine": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "My listings (native alias)", "description": "Alias of GET /api/v1/marketplace/me/listings. Native still calls this path.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { listings } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/listings/{id}": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Get a listing", "description": "Optional auth. Bare GET /api/v1/marketplace/{id} also resolves a listing (not documented as its own path).", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data: { listing } }" }, "404": { "description": "NOT_FOUND" } } }, "delete": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Cancel a listing", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } }, "patch": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Edit a listing", "description": "Requires a valid x-listing-pin-token for the caller. Seller-only edit of an active listing (#849 Opt A). Sale: salePrice, openToTradeOffers, tradeCriteria. Auction with no bids: startingBid, buyNowPrice, reservePrice, askingPrice, durationDays (recomputes endsAt). Auction with bids: startingBid/reservePrice/durationDays locked (409 LISTING_HAS_BIDS); only buyNowPrice lowering above currentBid and askingPrice. Trade: tradeCriteria, openToTradeOffers. Pack listings must still be sealed (409 PACK_ALREADY_OPENED). Reserve amount never serialized, only reserveMet.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-listing-pin-token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "PIN verification token. Missing or invalid → 401 PIN_TOKEN_INVALID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "salePrice": { "type": "integer", "minimum": 1 }, "openToTradeOffers": { "type": "boolean" }, "startingBid": { "type": "integer", "minimum": 1 }, "askingPrice": { "type": "integer", "minimum": 1, "nullable": true }, "buyNowPrice": { "type": "integer", "minimum": 1, "nullable": true }, "durationDays": { "type": "integer", "enum": [ 1, 3, 7, 14 ] }, "reservePrice": { "type": "integer", "minimum": 1, "nullable": true }, "tradeCriteria": { "type": "object" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{ success, data: { listing } }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED or PIN_TOKEN_INVALID" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT (incl. LISTING_HAS_BIDS, PACK_ALREADY_OPENED)" }, "503": { "description": "CONFIGURATION_ERROR (auth check failed)" } } } }, "/api/v1/marketplace/listings/{id}/bids": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Listing bid history", "description": "Optional auth.", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data: { bids } }" }, "404": { "description": "NOT_FOUND" } } }, "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Place a bid", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number" }, "walletAddress": { "type": "string", "description": "Bidder wallet stored for auction settlement (#942)." } } } } } }, "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/v1/marketplace/listings/{id}/buy": { "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Buy a listing now", "description": "Optional body `{ expectedPrice?, walletAddress?, settlementId? }`. walletAddress is the buyer's active wallet: the card lands in its default binder (#928); omitted = buyer's primary wallet. settlementId replays the same receipt. Success data includes status `settled`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedPrice": { "type": "number", "description": "Client price pin; conflicts when the seller raised since display." }, "walletAddress": { "type": "string", "description": "Active wallet the purchase runs in (#928)." }, "settlementId": { "type": "string", "description": "Idempotency key. 1-64 characters of letters, numbers, and . _ : -." } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data: { status: settled, settlementId? } }" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT, ITEM_LOCKED, or IDEMPOTENCY_KEY_CONFLICT" } } } }, "/api/v1/marketplace/listings/{id}/offers": { "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Send a trade offer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "offeredCardIds", "offeredPackIds" ], "properties": { "offeredCardIds": { "type": "array", "items": { "type": "string" } }, "offeredPackIds": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "expiresInDays": { "type": "integer", "enum": [ 1, 3, 7, 14, 30 ] } } } } } }, "responses": { "201": { "description": "{ success, data: { offer } }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/v1/marketplace/listings/{id}/subscribe": { "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Subscribe to listing updates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } }, "delete": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Unsubscribe from listing updates", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/marketplace/me/listings": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "My listings", "description": "Live path. Native alias: GET /api/v1/marketplace/listings/mine.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { listings } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/me/purchases": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "My purchases", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { purchases } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/me/sales": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "My sales", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { sales } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/offers/received": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Received trade offers", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { offers } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/offers/sent": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Sent trade offers", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { offers } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/offers/{id}": { "delete": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Withdraw a trade offer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/v1/marketplace/offers/{id}/accept": { "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Accept a trade offer", "description": "Optional body `{ walletAddress?, settlementId? }`: the acceptor's active wallet. When the acceptor receives the listed item it lands in that wallet's default binder (#928). settlementId replays the accept. Success data includes status `settled`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletAddress": { "type": "string", "description": "Acceptor's active wallet (#928)." }, "settlementId": { "type": "string", "description": "Idempotency key. 1-64 characters of letters, numbers, and . _ : -." } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT, ITEM_LOCKED, or IDEMPOTENCY_KEY_CONFLICT" } } } }, "/api/v1/marketplace/offers/{id}/counter": { "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Counter a trade offer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "offeredCardIds", "offeredPackIds" ], "properties": { "offeredCardIds": { "type": "array", "items": { "type": "string" } }, "offeredPackIds": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "expiresInDays": { "type": "integer", "enum": [ 1, 3, 7, 14, 30 ] } } } } } }, "responses": { "200": { "description": "{ success, data: { offer } }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/v1/marketplace/offers/{id}/reject": { "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Reject a trade offer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CONFLICT" } } } }, "/api/v1/marketplace/price-suggestion": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Suggested listing price", "description": "Public. itemId and itemType (card | pack) are required.", "security": [], "parameters": [ { "name": "itemId", "in": "query", "schema": { "type": "string" }, "required": true }, { "name": "itemType", "in": "query", "schema": { "type": "string", "enum": [ "card", "pack" ] }, "required": true } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "VALIDATION_ERROR" } } } }, "/api/v1/marketplace/promos": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Shop promos for the caller", "description": "Published, in-window promos for teams the caller follows, favorites, or has joined. Each promo carries nullable tag (uppercase badge), itemType (pack | card), and ctaLabel display fields. POST is staff / team-manager only and omitted from this public spec.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { promos } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/receipts/{receiptId}": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Get a marketplace receipt", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "receiptId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data: { receipt } }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/marketplace/search": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Unified marketplace search across listings and products", "description": "One ranked, paginated result list across active marketplace listings and catalogue products/packs. Each item spreads its family's existing card shape plus a `kind` discriminator (`listing` | `product`); every product item carries `createdAt` for recency interleaving. `family` selects the result families: `all`, `collectibles` (card listings + merch products) or `packs` (pack listings + packs). `listingType` and `auctionState` are dropped for `family=packs`. `minOvr`/`maxOvr` are accepted and ignored until a backing OVR field lands. `totalCount` is exact on the last page, a lower bound while `hasMore` (same convention as the list endpoints).", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "family", "in": "query", "schema": { "type": "string", "enum": [ "all", "collectibles", "packs" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "recent", "price-asc", "price-desc" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "listingType", "in": "query", "schema": { "type": "string", "enum": [ "sale", "auction", "trade", "all" ] } }, { "name": "auctionState", "in": "query", "schema": { "type": "string", "enum": [ "all", "ending-soon", "just-started", "has-bids" ] } }, { "name": "minPrice", "in": "query", "schema": { "type": "number" } }, { "name": "maxPrice", "in": "query", "schema": { "type": "number" } }, { "name": "minOvr", "in": "query", "schema": { "type": "number" }, "description": "Accepted and ignored until a backing OVR field lands" }, { "name": "maxOvr", "in": "query", "schema": { "type": "number" }, "description": "Accepted and ignored until a backing OVR field lands" }, { "name": "rarities", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated rarities" }, { "name": "teams", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated team ids" }, { "name": "leagues", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated league ids" }, { "name": "sport", "in": "query", "schema": { "type": "string" } }, { "name": "league", "in": "query", "schema": { "type": "string" } }, { "name": "team", "in": "query", "schema": { "type": "string" } }, { "name": "includeDemo", "in": "query", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "{ success, data: { items, totalCount, hasMore, page, limit } }" }, "400": { "description": "VALIDATION_ERROR" } } } }, "/api/v1/marketplace/suggested-collectibles": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Suggested collectible listings", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 8 } } ], "responses": { "200": { "description": "{ success, data: { listings } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/suggested-packs": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Suggested pack listings", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 8 } } ], "responses": { "200": { "description": "{ success, data: { listings } }" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/v1/marketplace/top-bids": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Top active auctions by bid count", "description": "Optional auth.", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 10 } } ], "responses": { "200": { "description": "{ success, data: { listings } }" } } } }, "/api/v1/marketplace/wishlist": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Get wishlist", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { entries } }" }, "401": { "description": "UNAUTHORIZED" } } }, "post": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Add to wishlist", "description": "Either listingId, or both itemType and itemId. By-item saves resolve to the newest active listing; with no active listing an item-backed row (listing null) is saved when the item exists.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string" }, "itemType": { "type": "string", "enum": [ "card", "pack" ] }, "itemId": { "type": "string" } } } } } }, "responses": { "201": { "description": "{ success, data }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/marketplace/wishlist/{entryId}": { "delete": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Remove a wishlist entry", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/user/kyc-status": { "get": { "tags": [ "KYC", "User" ], "summary": "Current KYC status", "description": "Status only. Lives under /api/v1/user, not marketplace. No vendor dashboard URLs.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { status, verifiedAt, identityVerificationId } }" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND" } } } }, "/api/wallets": { "get": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "List wallets", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ wallets } sorted by sortOrder, createdAt, id; each item includes sortOrder, label, color, icon, isHidden" } } }, "post": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Create or import wallet", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "pin" ], "properties": { "pin": { "type": "string", "pattern": "^\\d{6}$", "description": "Required for custodial create and import/link. Exactly 6 digits." }, "legalTermsVersion": { "type": "string", "description": "Required for custodial create" }, "address": { "type": "string", "description": "Required for import/link" }, "encryptedPrivateKey": { "type": "string" }, "privateKey": { "type": "string" }, "mnemonic": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ wallet }" } }, "description": "PIN is required for every create path. Custodial create: `{ pin, legalTermsVersion }` only — server generates secrets. Import/link: `pin` plus `address` plus `encryptedPrivateKey` or `privateKey` (optional `mnemonic`)." }, "delete": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Remove wallet", "description": "Custodial delete requires `{ address, pin }` (6 digits) in the same request. External links need only `{ address }`. Clerk lastActiveAt is not a gate. Last wallet may be deleted. Wrong PIN is 400 INVALID_PIN; missing PIN is 400 VALIDATION_ERROR. Optional `ack: { timestamp, walletAddress, binderCount?, cardCount?, unopenedPackCount?, openedPackCount?, countsUnknown?, copyVersion }` records the delete confirmation (#928): binders keep the removed address (hidden from wallet-scoped lists until the address is linked again) and the ack is stored durably. All four stored counts are server-computed truth; the client numbers (null/omitted when unknown) are stored in the corresponding shown* fields. If any shown numeric count is below current truth, deletion returns 409 WALLET_DELETE_ACK_REQUIRED with the current counts so the fan can review again. `countsUnknown: true` cannot accompany any numeric count. Malformed ack is 400 VALIDATION_ERROR; an ack naming another wallet is rejected.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "description": "0x-prefixed 40-hex Ethereum address" }, "pin": { "type": "string", "pattern": "^\\d{6}$", "description": "Required for CUSTODIAL wallets. Omit for EXTERNAL links." }, "ack": { "type": "object", "required": [ "timestamp", "walletAddress", "copyVersion" ], "properties": { "timestamp": { "type": "string", "description": "Client timestamp of the confirmation (ISO string)" }, "walletAddress": { "type": "string", "description": "Wallet the fan confirmed; must match address" }, "binderCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Binder count shown in the confirmation copy; null/omitted when unknown (#934). Stored as shownBinderCount; the stored binderCount is server-computed." }, "cardCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Card count shown in the confirmation copy; null/omitted when unknown (#934). Stored as shownCardCount; the stored cardCount is server-computed." }, "unopenedPackCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Unopened-pack count shown in the confirmation copy; null/omitted when unknown. Stored as shownUnopenedPackCount; the stored unopenedPackCount is server-computed." }, "openedPackCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Opened-pack count shown in the confirmation copy; null/omitted when unknown. Stored as shownOpenedPackCount; the stored openedPackCount is server-computed." }, "copyVersion": { "type": "string", "description": "Client copy version the fan acked" }, "countsUnknown": { "type": "boolean", "description": "True when the client could not determine any count. Contradicts any numeric count." } } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ message, wallets } — wallets is the remaining list sorted by sortOrder (compacted 0..n-1)" }, "400": { "description": "INVALID_PIN (wrong wallet PIN) or VALIDATION_ERROR (invalid address, missing PIN, PIN reset required, or malformed ack)" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND (wallet missing or not owned by the caller)" }, "409": { "description": "WALLET_DELETE_ACK_REQUIRED with current binderCount, cardCount, unopenedPackCount, and openedPackCount when the ack is omitted but holdings or last-linked-wallet status require confirmation, or when shown counts are stale. A known-empty non-last wallet is exempt." } } } }, "/api/wallets/order": { "put": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Persist wallet order", "description": "Edit-mode drag reorder (#888). Body `{ walletIds }`: the full ordered list of the caller's wallet ids (1..50, unique). Atomic, owner-scoped by id, idempotent, no PIN. 30 req/min/user (429 RATE_LIMITED with Retry-After).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "walletIds" ], "properties": { "walletIds": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string" }, "description": "Full ordered list of the caller's wallet ids" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ wallets } in the new display order" }, "400": { "description": "VALIDATION_ERROR (empty array, oversized, duplicates)" }, "401": { "description": "UNAUTHORIZED" }, "409": { "description": "WALLET_SET_CHANGED (ids do not equal the caller's set) with current { wallets } for merge-and-retry" }, "429": { "description": "RATE_LIMITED (30/min) with Retry-After" }, "500": { "description": "INTERNAL_ERROR (untyped action failure)" } } } }, "/api/wallets/by-id/{id}": { "patch": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Update wallet display metadata", "description": "Edit-mode metadata (#888). At least one of `label` (<=40 chars, empty clears), `color` (#RRGGBB, null clears), `icon` (1..64 chars, null clears), `isHidden`. Owner-scoped by wallet id.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Wallet database id of a wallet the caller owns.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "maxLength": 40, "description": "User-set display name; empty string clears" }, "color": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$", "description": "User-set accent color" }, "icon": { "type": [ "string", "null" ], "maxLength": 64, "description": "User-set icon key" }, "isHidden": { "type": "boolean", "description": "Soft-hide from the carousel" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ wallet } — the updated wallet list item" }, "400": { "description": "VALIDATION_ERROR (empty patch or malformed field)" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND (wallet missing or not owned by the caller)" }, "500": { "description": "INTERNAL_ERROR (untyped action failure)" } } } }, "/api/wallets/coin-prices": { "get": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Get coin prices", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Coin prices" } } } }, "/api/wallets/private-key": { "post": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Deprecated: fetch private key (PIN-gated)", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "INVALID_PIN (wrong wallet PIN) or VALIDATION_ERROR (malformed input, missing PIN, or PIN reset required)" } }, "deprecated": true, "description": "Deprecated. Use POST /api/wallets/{address}/sign-transaction for sends and POST /api/wallets/{address}/export for seed reveal." } }, "/api/wallets/set-pin": { "post": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Set PIN", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/wallets/verify-pin": { "post": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Verify PIN", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" } } } }, "/api/wallets/{address}/holdings": { "get": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "Get linked wallet holdings", "description": "Returns strict case-insensitive counts for binders, cards, unopened packs, and opened packs in the linked wallet.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } ], "responses": { "200": { "description": "Wallet holdings", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/WalletHoldings" } } } } } }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "WALLET_NOT_LINKED" } } } }, "/api/wallets/{address}/export": { "post": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "PIN-gated custodial seed/key export", "description": "Replacement for deprecated POST /api/wallets/private-key. Reveals signing material after PIN check.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pin" ], "properties": { "pin": { "type": "string", "pattern": "^\\d{6}$" } } } } } }, "responses": { "200": { "description": "{ success: true, data: { privateKey, mnemonic } }" }, "400": { "description": "INVALID_PIN (wrong wallet PIN) or VALIDATION_ERROR (malformed input, missing PIN, or PIN reset required)" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/wallets/{address}/sign-transaction": { "post": { "tags": [ "Wallets", "Wallet and web3" ], "summary": "PIN-gated custodial sign and send", "description": "Signs and broadcasts server-side. Private key never leaves the server. Returns { txHash, chainId }.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pin", "to", "value", "chainId" ], "properties": { "pin": { "type": "string", "pattern": "^\\d{6}$" }, "to": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "value": { "type": "string", "pattern": "^\\d+$" }, "data": { "type": "string", "pattern": "^0x([a-fA-F0-9]{2})*$" }, "chainId": { "type": "integer" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } } } } }, "responses": { "200": { "description": "{ success: true, data: { txHash, chainId } }" }, "400": { "description": "INVALID_PIN (wrong wallet PIN) or VALIDATION_ERROR (malformed input, missing PIN, or PIN reset required)" }, "401": { "description": "UNAUTHORIZED" } } } }, "/api/webhooks/revenuecat": { "post": { "tags": [ "Webhooks", "Commerce and purchases" ], "summary": "RevenueCat webhook", "description": "Grants coins on NON_RENEWING_PURCHASE. product_id may be a store SKU (com.engage.coins_*) or a legacy tier_*_coins id. An unknown coin product returns 500 UNKNOWN_PRODUCT. CANCELLATION with cancel_reason CUSTOMER_SUPPORT claws back a coin grant (balance may go negative; free price-0 claims still succeed). Unmatched coin refunds return 500 PURCHASE_NOT_FOUND. REFUND_REVERSED re-credits a refunded coin grant once (App Store). Use Authorization: Bearer with REVENUECAT_WEBHOOK_SECRET.", "security": [ { "webhookSecret": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "required": [ "id" ], "properties": { "type": { "type": "string" }, "id": { "type": [ "string", "null" ], "description": "RevenueCat event id. The key is always present; the value can be null. Retries reuse it. A coin refund with a missing or empty id returns 400." }, "app_user_id": { "type": "string" }, "product_id": { "type": "string" }, "transaction_id": { "type": "string" }, "original_transaction_id": { "type": "string", "description": "Preferred match key for the original coin grant." }, "cancel_reason": { "type": "string", "description": "On CANCELLATION, CUSTOMER_SUPPORT is a refund." }, "currency": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "{ received: true }" }, "400": { "description": "VALIDATION_ERROR — invalid payload, a purchase with no transaction id, or a coin refund or reversal with no event id" }, "401": { "description": "UNAUTHORIZED" }, "500": { "description": "INTERNAL_ERROR, PURCHASE_NOT_FOUND when a coin refund matches no grant, or UNKNOWN_PRODUCT when the coin SKU is not seeded" } } } }, "/api/v1/engage/quests/arena-check-in": { "post": { "tags": [ "Quests", "Engage" ], "summary": "Claim arena check-in", "description": "Daily arena check-in for one team. Body: { teamId }. Revalidates the leaderboard tag on success.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "teamId is required" }, "401": { "description": "Authentication required" } } } }, "/api/v1/engage/quests/daily-summary": { "get": { "tags": [ "Quests", "Engage" ], "summary": "Daily quest summary", "description": "Per-followed-team daily checklist (no question/options).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/engage/quests/{questId}/session": { "post": { "tags": [ "Quests", "Engage" ], "summary": "Open daily quiz session", "description": "Opens a locked daily quiz session (question + options only).", "parameters": [ { "name": "questId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/engage/quests/session/{sessionId}/submit": { "post": { "tags": [ "Quests", "Engage" ], "summary": "Submit quiz answer", "description": "Body: { answerIndex: number }.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/engage/quests/session/{sessionId}/forfeit": { "post": { "tags": [ "Quests", "Engage" ], "summary": "Forfeit quiz session", "description": "Forfeits an open daily quiz session.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/engage/game-services/link": { "post": { "tags": [ "Engage" ], "summary": "Link a Game Center or Play Games identity", "description": "Verifies the provider proof, links the globally unique player ID to the authenticated Clerk user, and best-effort mirrors the link to Clerk private metadata.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "platform", "publicKeyUrl", "signature", "salt", "timestamp", "playerId", "bundleId" ], "properties": { "platform": { "type": "string", "const": "gameCenter" }, "publicKeyUrl": { "type": "string", "format": "uri" }, "signature": { "type": "string" }, "salt": { "type": "string" }, "timestamp": { "type": "integer" }, "playerId": { "type": "string", "minLength": 1 }, "bundleId": { "type": "string" } } }, { "type": "object", "required": [ "platform", "serverAuthCode", "playerId" ], "properties": { "platform": { "type": "string", "const": "playGames" }, "serverAuthCode": { "type": "string", "minLength": 1 }, "playerId": { "type": "string", "minLength": 1 } } } ] } } } }, "responses": { "200": { "description": "{ success, data: { platform, playerId, linkedAt } }" }, "400": { "description": "INVALID_PROOF" }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "NOT_FOUND — the authenticated Clerk user has no local User record." }, "409": { "description": "PLAYER_LINKED_ELSEWHERE" }, "503": { "description": "PROVIDER_UNAVAILABLE" } } } }, "/api/v1/engage/rep/earn": { "post": { "tags": [ "Rep", "Engage" ], "summary": "Record client Rep earn", "description": "Body: { earnKind, idempotencyKey, targetId? }. Successful earns may return gameServices.fanPoints: { total, seasonTotal } when the best-effort Fan Rep lookup succeeds.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data with optional gameServices: { fanPoints?: { total, seasonTotal } } }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/v1/engage/rep/me": { "get": { "tags": [ "Rep", "Engage" ], "summary": "My Club Rep per team", "description": "Club Rep progress ({ teamId, points, level, pct }) for the given teams. Repeatable teamId param.", "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Repeatable. Team to report Rep for." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/engage/rep/player/me": { "get": { "tags": [ "Rep", "Engage" ], "summary": "My Player Rep per player", "description": "Player Rep progress ({ playerId, points, level, pct }) for the given players. Parallel to Club Rep; kept separate. Repeatable playerId param.", "parameters": [ { "name": "playerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Repeatable. Player to report Rep for." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/engage/player-challenge/complete": { "post": { "tags": [ "Games", "Engage" ], "summary": "Player challenge complete (retired)", "description": "Retired anti-farming removal: client-asserted wins are no longer accepted. Always 410 GONE; Rep is awarded server-side on verified Guess-the-Player wins.", "security": [], "responses": { "410": { "description": "Retired; Rep is awarded automatically" } } } }, "/api/events/{gameId}/chat/read": { "put": { "tags": [ "Events" ], "summary": "Persist chat read cursor", "description": "Persists the viewer's read cursor for the NEW divider. Body: { messageId? }.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/events/{gameId}/chat/{messageId}/react": { "post": { "tags": [ "Events" ], "summary": "Toggle chat reaction", "description": "Body: { emoji }. Toggles the viewer's reaction on a game-thread message in this gameId. New pills must be one emoji grapheme (RGI, or a text-style / emoji-presentation variant), at most 64 UTF-16 units, stored exactly as sent (no FE0F folding). At most 20 distinct pills per message; joining an existing pill is allowed. Legacy stored values can still be toggled off. Codes: 400 VALIDATION_ERROR (blank), 400 INVALID_EMOJI, 404 NOT_FOUND (missing or wrong game), 409 MESSAGE_REMOVED, 409 REACTION_EMOJI_LIMIT, 429 RATE_LIMITED (20/10s burst and 120/10min sustained per user), 503 RATE_LIMITER_UNAVAILABLE. Each new unique user+message+emoji credits +1 Fan Rep once.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/locker-room/comments/{commentId}/react": { "get": { "tags": [ "Locker room" ], "summary": "Get comment reactions", "description": "Reaction summary for one locker-room comment.", "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "Locker room" ], "summary": "Toggle comment reaction", "description": "Toggles the viewer's reaction on a locker-room comment.", "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/locker-room/{id}/comments/{commentId}": { "put": { "tags": [ "Locker room" ], "summary": "Edit comment", "description": "Edits the caller's own comment. Body: { content, mentionedUserIds?: string[] }. Omitting mentionedUserIds (or sending null) leaves existing mentions untouched; send an explicit [] to clear them. Responses echo mentions[].", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "delete": { "tags": [ "Locker room" ], "summary": "Delete comment", "description": "Deletes the caller's own comment (or by moderation).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/moderation/reports": { "post": { "tags": [ "Moderation and reporting" ], "summary": "File moderation report", "description": "Body: report type (INAPPROPRIATE_NAME, INAPPROPRIATE_CONTENT, SPAM, HARASSMENT, …) plus target.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/me/starred-teams": { "get": { "tags": [ "Teams" ], "summary": "List starred HQ teams", "description": "The authenticated user's starred clubs — bookmarks, not follows. Each entry: { id, slug, name, logo, source, providerId, starredAt }. slug/name/logo resolve live from Team when a row exists and fall back to the stored client snapshot, so provider clubs without a synced Team row still render — and all three are nullable (snapshot-less rows and unresolved provider clubs can carry nulls). source/providerId are null when no Team row exists.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { teams: StarredTeamInfo[] } }" }, "401": { "description": "Authentication required" } } }, "post": { "tags": [ "Teams" ], "summary": "Merge starred teams snapshot", "description": "Additive bulk merge — the one-time MMKV migration path for engage-native. Existing ids refresh their stored snapshot; new ids are starred until the 50-club cap; entries past the cap are counted in `skipped` rather than failing, with per-entry detail in `rejected` ([{ id, reason }], reason 'invalid' | 'over_cap', input order; `skipped` semantics unchanged). Body: { teams: [{ id, slug?, name?, logo? }] }.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teams" ], "properties": { "teams": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { teams, added, skipped, rejected: [{ id: string | null, reason: 'invalid' | 'over_cap' }] } }" }, "400": { "description": "VALIDATION_ERROR — teams must be an array" }, "401": { "description": "Authentication required" } } } }, "/api/me/starred-teams/{teamId}": { "put": { "tags": [ "Teams" ], "summary": "Star a team", "description": "Idempotent bookmark — a star is not a follow and grants no social surface, so provider clubs are allowed. teamId need not resolve to a Team row yet. Optional body { slug?, name?, logo? } stores the client display snapshot; re-starring refreshes only the keys sent, and an explicit null clears a stored value. New stars past the 50-club cap return 409 STARRED_TEAMS_LIMIT.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { starred: true, team } }" }, "400": { "description": "VALIDATION_ERROR — teamId is required" }, "401": { "description": "Authentication required" }, "409": { "description": "STARRED_TEAMS_LIMIT — 50-club cap reached for a new id" } } }, "delete": { "tags": [ "Teams" ], "summary": "Unstar a team", "description": "Idempotent — deleting a star that does not exist still returns success.", "parameters": [ { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { starred: false } }" }, "400": { "description": "VALIDATION_ERROR — teamId is required" }, "401": { "description": "Authentication required" } } } }, "/api/me/custom-formations": { "get": { "tags": [ "Teams" ], "summary": "List custom formations", "description": "The fan's saved formation templates, newest first (#847) - the cross-device sync target for the native device-local custom-formations store. Optional ?sport= filter (hockey|soccer|basketball|football|baseball).", "parameters": [ { "name": "sport", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { formations: [{ id, sport, name, presetKey, slots, createdAt, updatedAt }] } }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "Authentication required" } } }, "post": { "tags": [ "Teams" ], "summary": "Create custom formation", "description": "Save a formation template (#847). Body: { sport, name, presetKey, slots }. Names are unique per sport; at most 20 templates per sport (CUSTOM_FORMATION_LIMIT).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sport", "name", "presetKey", "slots" ], "properties": { "sport": { "type": "string" }, "name": { "type": "string" }, "presetKey": { "type": "string" }, "slots": { "type": "object", "description": "Record - opaque to the backend, at most 30 entries." } }, "description": "{ sport, name, presetKey, slots }" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "{ success, data: formation }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "Authentication required" }, "409": { "description": "CONFLICT or CUSTOM_FORMATION_LIMIT" } } } }, "/api/me/custom-formations/{id}": { "get": { "tags": [ "Teams" ], "summary": "Get custom formation", "description": "Read one saved template (#847). Another fan's id reads as 404, never 403.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: formation }" }, "401": { "description": "Authentication required" }, "404": { "description": "Formation not found" } } }, "patch": { "tags": [ "Teams" ], "summary": "Update custom formation", "description": "Last-write-wins partial update - any of sport, name, presetKey, slots (#847). Renames keep per-sport uniqueness; moves to a full sport fail with CUSTOM_FORMATION_LIMIT.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sport": { "type": "string" }, "name": { "type": "string" }, "presetKey": { "type": "string" }, "slots": { "type": "object", "description": "Record - opaque to the backend, at most 30 entries." } }, "description": "Partial { sport?, name?, presetKey?, slots? }" } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: formation }" }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "Authentication required" }, "404": { "description": "Formation not found" }, "409": { "description": "CONFLICT or CUSTOM_FORMATION_LIMIT" } } }, "delete": { "tags": [ "Teams" ], "summary": "Delete custom formation", "description": "Idempotent delete - a missing id still succeeds with deleted: false (#847).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { id, deleted } }" }, "401": { "description": "Authentication required" } } } }, "/api/invites/me": { "get": { "tags": [ "User" ], "summary": "Get-or-create my referral code", "description": "Any authenticated user. First tap of Invite friends creates the row.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: InviteMeView }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMeSuccess" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } } } }, "post": { "tags": [ "User" ], "summary": "Create my referral code", "description": "Same as GET — first tap of Invite friends creates the row.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: InviteMeView }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMeSuccess" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } } } } }, "/api/invites/{code}": { "get": { "tags": [ "User" ], "summary": "Validate invite code", "description": "Public validate. Never leaks VIP issuer identity.", "security": [], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "code", "in": "path" } ], "responses": { "200": { "description": "{ success, data: InvitePublicView }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitePublicSuccess" } } } }, "400": { "description": "Invite code is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } }, "404": { "description": "Invite code not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } } } } }, "/api/invites/{code}/redeem": { "post": { "tags": [ "User" ], "summary": "Redeem invite code", "description": "Clerk-authenticated. New signups only.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "code", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemInviteBody" } } } }, "responses": { "200": { "description": "{ success, data: InviteRedeemView }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteRedeemSuccess" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } }, "404": { "description": "Invite code or user not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } }, "409": { "description": "Already redeemed, revoked, expired, or exhausted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } } } } }, "/api/news": { "get": { "tags": [ "Feed" ], "summary": "List news articles", "description": "Public list of published news articles (newest first). Team HQ sections also receive the team's published public posts as `data.posts` (#827) unless `includePosts=false`, which restores the pre-#827 `{ articles }` payload. `limit` caps each array. Post items carry `itemType: \"post\"` plus team identity, media, counts, and ISO `createdAt`; merge with `articles` client-side by date for one list.", "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to one team." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Max rows." }, { "name": "includeDemo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include demo rows." }, { "name": "includePosts", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include team posts (default true). `false` omits the `posts` key." } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/news/{id}": { "get": { "tags": [ "Feed" ], "summary": "Get news article", "description": "Single published news article. Public.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/pins": { "get": { "tags": [ "Locker room" ], "summary": "List pin rail", "description": "Public locker-room pin rail (moderator-curated).", "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to one team." }, { "name": "includeDemo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include demo rows." } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/prompts": { "get": { "tags": [ "Feed" ], "summary": "List prompt catalog", "description": "Public prompt catalog for in-feed engagement questions.", "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to one team." }, { "name": "includeDemo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include demo rows." } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/user/binder-covers": { "get": { "tags": [ "User" ], "summary": "List my binder covers", "description": "The caller's binder-cover library (newest first). Built covers (dsc1. renders) are excluded. Persist real https URLs only.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/user/data-export": { "get": { "tags": [ "User" ], "summary": "List my data exports", "description": "The caller's data-export requests, newest first (at most 50). When a row is COMPLETED and metadata.expiresAt is still in the future, downloadUrl is a freshly minted signed URL (about 1 hour) for the private fan-data-exports object. Expired, failed, and in-progress rows return downloadUrl null. metadata.expiresAt and metadata.emailSkipped are safe for clients. Storage keys are never returned.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "User" ], "summary": "Request data export", "description": "Creates a zip data-export request for the caller (format zip, status REQUESTED). An open REQUESTED or PROCESSING row is returned with 200 and is not duplicated. After a terminal row, a second request inside 24 hours is 429 RATE_LIMITED. The body does not accept email. Optional metadata.reason is a string up to 500 characters. The archive is built by GET /api/cron/data-export.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data } existing open REQUESTED or PROCESSING row" }, "201": { "description": "{ success, data } newly created request" }, "400": { "description": "Validation error (email is not accepted, or reason is invalid)" }, "401": { "description": "Authentication required" }, "429": { "description": "{ success: false, error, code: RATE_LIMITED } with Retry-After" }, "503": { "description": "{ success: false, error, code: RATE_LIMITER_UNAVAILABLE }" } } } }, "/api/user/follow-requests": { "get": { "tags": [ "User" ], "summary": "List incoming follow requests", "description": "Pending follow requests for the authenticated (private) account owner. Supports page/limit. data: { requests: [{ id, createdAt, requester: { id, name, handle, profileUrl, profileUrlThumbhash, favoriteTeam } }], total }. requester.favoriteTeam is the raw User.favoriteTeam (\"\" when unset), as user search returns it.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1-based page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Page size." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/user/follow-requests/{id}": { "delete": { "tags": [ "User" ], "summary": "Withdraw follow request", "description": "Requester withdraws a pending request.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" } } } }, "/api/user/follow-requests/{id}/approve": { "post": { "tags": [ "User" ], "summary": "Approve follow request", "description": "Idempotent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" } } } }, "/api/user/follow-requests/{id}/deny": { "post": { "tags": [ "User" ], "summary": "Deny follow request", "description": "Denies a pending follow request.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" } } } }, "/api/user/nfts/pending": { "get": { "tags": [ "User" ], "summary": "List pending NFT mints", "description": "The caller's unminted NFT queue.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "User" ], "summary": "Batch-mint pending NFTs", "description": "Body: { recipientAddress }. Mints the caller's pending queue.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/user/packs/{purchaseId}": { "patch": { "tags": [ "User" ], "summary": "Set pack binder target", "description": "Set or clear Open Later targetBinderId on an unopened pack purchase. Body: { targetBinderId: string | null }.", "parameters": [ { "name": "purchaseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/user/points-history": { "get": { "tags": [ "User" ], "summary": "Points history", "description": "Ledger rows ({ id, points, completedAt, reason, questId }) for the caller.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/user/push-subscriptions": { "get": { "tags": [ "User" ], "summary": "List push subscriptions", "description": "The caller's push subscriptions (newest first).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "User" ], "summary": "Create push subscription", "description": "Upserts the caller's push subscription. Body: { platform (required), provider?, externalSubscriptionId?, pushToken?, isEnabled?, metadata? }. A non-blank externalSubscriptionId is trimmed and upserted on that id, and the row's userId moves to the caller so a device signed into another account stops receiving the previous account's pushes. A missing or blank id updates or creates the legacy null-id row for that caller and platform. Returns 201.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } }, "delete": { "tags": [ "User" ], "summary": "Delete push subscription", "description": "Removes the caller's push subscription. Query platform is required. Optional body: { externalSubscriptionId }. When that id is non-blank it is trimmed and only that device is deleted; a missing, empty, or invalid body removes every row for the caller on that platform. Another account's device is never deleted.", "parameters": [ { "name": "platform", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Device platform, for example ios or android." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/user/support/tickets": { "get": { "tags": [ "User" ], "summary": "List support tickets", "description": "The caller's support tickets.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "User" ], "summary": "Open support ticket", "description": "Body: category (support/bug/…) plus message. Sends confirmation email when configured.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/user/support/tickets/{id}/messages": { "get": { "tags": [ "User" ], "summary": "List ticket messages", "description": "Messages on the caller's ticket.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } }, "post": { "tags": [ "User" ], "summary": "Post ticket message", "description": "Appends a message to the caller's ticket.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/teams/{id}/achievements": { "get": { "tags": [ "Teams" ], "summary": "Get team achievements", "description": "Public. Returns the team's achievements/badges.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/commerce": { "get": { "tags": [ "Commerce and purchases" ], "summary": "Team commerce block", "description": "Team tickets / merch / sponsors / promoted block. Public. ?teamId= or ?team=slug. Promoted item owner is {kind:'platform', partner?} or {kind:'team', teamId, teamSlug, partner?} (teamSlug is additive; team items still include teamId). An authenticated viewer's creative feed preferences (#722) are omitted from promoted after that owner is resolved (both less and never, because this list has no score). Organic preferences do not change this payload, and preference rows are not written to AdImpression.", "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Team id." }, { "name": "team", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Team slug." }, { "name": "placement", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Thin selector over the same sponsor inventory (e.g. below-headline, link-top)." } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/dsports-cash/ledger": { "get": { "tags": [ "D-Sports Cash", "Commerce and purchases" ], "summary": "Cash movement history", "description": "Coin movement history (?limit=, default 50). Balance source of truth remains GET /api/dsports-cash.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Max rows (default 50)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/market/promos": { "get": { "tags": [ "Marketplace", "Commerce and purchases" ], "summary": "Market promos", "description": "Thin alias of GET /api/v1/marketplace/promos — same eligibility logic.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/packs/{id}/odds": { "get": { "tags": [ "Packs", "Collectibles and packs" ], "summary": "Pack pull odds", "description": "Per-rarity pull odds plus guarantee for one pack. Public.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" }, "404": { "description": "Not found" } } } }, "/api/packs/{id}/opening-manifest": { "get": { "tags": [ "Packs", "Collectibles and packs" ], "summary": "Pack opening manifest", "description": "Cacheable pack-opening scene payload: template, slot art, fallback video, odds, card-back branding and assetVersion. Public. Optional `audio` carries static scene tuning (pack audioJson wins over team default; omitted when neither configures it) and rotates assetVersion; no outcome data. A meshopt-compressed template (Pack.glbMinScene 3) is omitted (`template: null`, `sceneEligible: false`) unless the host sends `scene` >= 3; uncompressed templates are served to every host.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scene", "in": "query", "required": false, "description": "Host scene level, an integer 0-99 (the v3 app sends 3). Absent or invalid is treated as no level. The response varies by this value.", "schema": { "type": "integer", "minimum": 0, "maximum": 99 } } ], "security": [], "responses": { "200": { "description": "{ success, data }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "audio": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "masterGain": { "type": "number" }, "cues": { "type": "object" }, "assetVersion": { "type": "string" } }, "required": [ "enabled", "assetVersion" ] }, "backdropColour": { "type": "string", "enum": [ "tier", "neutral" ], "description": "Backdrop pattern colouring for the 3D pack-opening scene (#1156): tier is rarity-coloured, neutral is grey. The pack value wins over the team default; omitted (never null) when neither is set. Not part of assetVersion." } } } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Not found" } } } }, "/api/v1/exchange-rate": { "get": { "tags": [ "D-Sports Cash", "Commerce and purchases" ], "summary": "CHF exchange rate", "description": "CHF <-> D-Sports Cash rate for the mobile BuyConfirmSheet. User-facing (not the admin revenue-fx route).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/product_entitlement_mapping": { "get": { "tags": [ "Commerce and purchases" ], "summary": "Entitlement mapping", "description": "Entitlement mapping generated from D-Sports Cash tiers. Public.", "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/user/set-pin": { "post": { "tags": [ "Marketplace" ], "summary": "Set listing PIN", "description": "Sets (or replaces) the caller's 6-digit marketplace listing PIN. Body: { pin }.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/v1/user/verify-pin": { "post": { "tags": [ "Marketplace" ], "summary": "Verify listing PIN", "description": "Verifies the caller's listing PIN; returns a short-lived X-Listing-Pin-Token. 404 PIN_NOT_SET until set-pin. Body: { pin }.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" } } } }, "/api/v1/users/contacts/match": { "post": { "tags": [ "User" ], "summary": "Match contacts", "description": "Body: { hashes: string[] } — sha256 digests only, never persisted. Max 100 matches.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { matches } }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/pregen-wallet": { "post": { "tags": [ "Wallet and web3" ], "summary": "Pregenerate in-app wallet", "description": "Triggers pregeneration of the caller's in-app wallet. Optional body: { userId } (admin use).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/thirdweb-link": { "post": { "tags": [ "Wallet and web3" ], "summary": "Create thirdweb link", "description": "Body: { payload }. Returns { userId, email } plus a session header; 401 without a session.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ userId, email } + session header" }, "400": { "description": "Payload missing" }, "401": { "description": "Authentication required" } } } }, "/api/thirdweb-proxy": { "get": { "tags": [ "Wallet and web3" ], "summary": "Proxy thirdweb RPC", "description": "Proxies GET to an allowlisted thirdweb origin via ?url=. 400 for missing/non-allowlisted urls.", "parameters": [ { "name": "url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Upstream URL (allowlisted origins only)." } ], "security": [], "responses": { "200": { "description": "Upstream body" }, "400": { "description": "Invalid or missing url" } } }, "post": { "tags": [ "Wallet and web3" ], "summary": "Proxy thirdweb POST", "description": "POST counterpart of the allowlisted thirdweb proxy.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Upstream body" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" } } } }, "/api/wallets/link-challenge": { "get": { "tags": [ "Wallets" ], "summary": "Create wallet-link challenge", "description": "One-time SIWE-style message for linking an external wallet.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/wallets/link-external": { "post": { "tags": [ "Wallets" ], "summary": "Link external wallet", "description": "Body: { challengeId, message, signature }.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/wallets/reset-pin": { "post": { "tags": [ "Wallets" ], "summary": "Reset wallet PIN", "description": "Reverification-gated wallet PIN reset.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/wallets/{address}/attestation": { "get": { "tags": [ "Wallets" ], "summary": "Get wallet attestation", "description": "Returns the D-Sports-signed wallet attestation JWS. The path value is the wallet database ID (not the on-chain address).", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/upload/binder-cover": { "post": { "tags": [ "User" ], "summary": "Upload binder cover", "description": "Multipart image (jpeg/png/webp/gif, max 10 MB) for binder covers.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/upload/locker-media": { "post": { "tags": [ "User" ], "summary": "Upload locker-room media", "description": "Multipart media for locker-room posts (UGC terms gated). `file` is a JPEG/PNG/WebP/GIF image (≤8MB) or MP4/MOV/WebM video (≤40MB); optional `poster` is a client-supplied video thumbnail image. For videos without a decodable supplied poster the server extracts a real frame server-side; when extraction fails the solid placeholder PNG is stored instead — the upload still succeeds. `data.posterKind` (`supplied` | `extracted` | `placeholder`) reports video poster provenance and is present only when `type` is `video`; photo responses omit it. Provenance is also recorded server-side in the upload ledger and persisted on the media row at post create — clients never submit it.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Image (JPG/PNG/WebP/GIF, ≤8MB) or video (MP4/MOV/WebM, ≤40MB)" }, "poster": { "type": "string", "format": "binary", "description": "Optional client-supplied video poster image (JPG/PNG/WebP/GIF)" } } } } } }, "responses": { "200": { "description": "{ success, data: { url, type, thumbnailUrl, posterKind? } } — `posterKind` present only for `type: \"video\"`; extraction failure still returns 200 with `posterKind: \"placeholder\"`", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "Public blob URL of the uploaded media" }, "type": { "type": "string", "enum": [ "photo", "video" ] }, "thumbnailUrl": { "type": "string", "description": "Poster/thumbnail blob URL (equals `url` for photos)" }, "posterKind": { "type": "string", "enum": [ "supplied", "extracted", "placeholder" ], "description": "Video poster provenance; omitted for photos" } }, "required": [ "url", "type", "thumbnailUrl" ] } } } } } }, "400": { "description": "Validation error (missing/invalid/oversized file)" }, "401": { "description": "Authentication required" }, "403": { "description": "UGC terms not accepted" } } } }, "/api/upload/profile": { "post": { "tags": [ "User" ], "summary": "Upload profile photo", "description": "Multipart image; replaces the caller's photo (old blob deleted, thumbhash computed).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data }" }, "400": { "description": "Validation error" }, "401": { "description": "Authentication required" } } } }, "/api/mobile/version": { "get": { "tags": [ "Config" ], "summary": "Mobile version gate", "description": "Version-gate + invite flags for native clients (60s cached). Public.", "security": [], "responses": { "200": { "description": "{ success, data: MobileVersionData }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MobileVersionSuccess" } } } }, "404": { "description": "App version config not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } }, "500": { "description": "Failed to load app version config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchGateError" } } } } } } }, "/api/mobile/wallet-callback": { "get": { "tags": [ "Mobile auth" ], "summary": "Wallet callback redirect", "description": "Universal/App Link target for the Coinbase Wallet SDK; redirects to the engagenative:// scheme. Reads no input.", "security": [], "responses": { "200": { "description": "Redirect to engagenative://wallet-callback" } } } }, "/api/health": { "get": { "tags": [ "Platform and infrastructure" ], "summary": "Liveness probe", "description": "Deliberately trivial: no database, no auth. Answers only whether the runtime booted. Public.", "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/games/daily-spin/reward": { "post": { "deprecated": true, "tags": [ "Games" ], "summary": "Daily-spin reward (deprecated)", "description": "Compat adapter: client-asserted awards are retired (points issue at engine time). Native must not call this; slated for 410 after the force-update minimum passes Wave 0.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data } (legacy)" }, "401": { "description": "Authentication required" } } } }, "/api/admin/card-value": { "get": { "tags": [ "Admin", "Collectibles and packs" ], "summary": "Get card value tables", "description": "Platform admin or superadmin only (isPlatformAdmin); moderators and club managers are forbidden. Optional teamId accepts an id or slug and returns the canonical team id, only stored team overrides, and complete effective bases. Omitted or blank teamId selects platform settings. No pagination. Responses are private, no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Team id or slug; omitted or blank selects platform settings. Unknown teams return NOT_FOUND." } ], "responses": { "200": { "description": "Card value tables", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/CardValueSettings" }, { "type": "object", "properties": { "platformRarityBases": { "required": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC" ] }, "effectiveRarityBases": { "required": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC" ] }, "momentFactors": { "required": [ "PORTRAIT", "ACTION", "MILESTONE", "GAME_WINNER" ] } } } ] } } }, "example": { "success": true, "data": { "platformRarityBases": { "COMMON": 10, "RARE": 50, "EPIC": 150, "LEGENDARY": 500, "MYTHIC": 1500 }, "teamId": null, "teamRarityBases": null, "effectiveRarityBases": { "COMMON": 10, "RARE": 50, "EPIC": 150, "LEGENDARY": 500, "MYTHIC": 1500 }, "momentFactors": { "PORTRAIT": 1, "ACTION": 1.25, "MILESTONE": 1.75, "GAME_WINNER": 2 } } } } }, "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } } }, "401": { "description": "Authentication required", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED" ] } } } } } }, "403": { "description": "Authenticated caller is neither admin nor superadmin (FORBIDDEN); club membership is insufficient.", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } }, "404": { "description": "Team not found (NOT_FOUND)", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "NOT_FOUND" ] } } } } } }, "500": { "description": "Settings read or transaction failed (INTERNAL_ERROR)", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } } } }, "put": { "tags": [ "Admin", "Collectibles and packs" ], "summary": "Edit card value tables", "description": "Platform admin or superadmin only (isPlatformAdmin). All writes run in one transaction, followed by a settings reread. Platform scope: integer rarity bases 0-1000000 and/or moment factors rounded to 2 decimal places before checking the stored range 0.1-10 (for example 0.095 stores 0.1 and 10.004 stores 10); teamId is forbidden. Team scope: nonblank teamId (id or slug) and rarity bases; null deletes an override and restores platform fallback, including when already absent. momentFactors is forbidden in team scope. At least one map entry is required. Unknown rarity/moment map keys are rejected; unrecognized top-level fields are ignored. Responses are private, no-store.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "scope" ], "properties": { "scope": { "type": "string", "enum": [ "platform" ] }, "rarityBases": { "type": "object", "additionalProperties": false, "properties": { "COMMON": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "RARE": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "EPIC": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "LEGENDARY": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "MYTHIC": { "type": "integer", "minimum": 0, "maximum": 1000000 } } }, "momentFactors": { "type": "object", "additionalProperties": false, "properties": { "PORTRAIT": { "type": "number", "minimum": 0.095, "exclusiveMaximum": 10.005, "description": "Rounded with Math.round(value * 100) / 100 before validating the stored range 0.1 through 10 inclusive." }, "ACTION": { "type": "number", "minimum": 0.095, "exclusiveMaximum": 10.005, "description": "Rounded with Math.round(value * 100) / 100 before validating the stored range 0.1 through 10 inclusive." }, "MILESTONE": { "type": "number", "minimum": 0.095, "exclusiveMaximum": 10.005, "description": "Rounded with Math.round(value * 100) / 100 before validating the stored range 0.1 through 10 inclusive." }, "GAME_WINNER": { "type": "number", "minimum": 0.095, "exclusiveMaximum": 10.005, "description": "Rounded with Math.round(value * 100) / 100 before validating the stored range 0.1 through 10 inclusive." } } }, "teamId": false }, "anyOf": [ { "required": [ "rarityBases" ], "properties": { "rarityBases": { "minProperties": 1 } } }, { "required": [ "momentFactors" ], "properties": { "momentFactors": { "minProperties": 1 } } } ] }, { "type": "object", "required": [ "scope", "teamId", "rarityBases" ], "properties": { "scope": { "type": "string", "enum": [ "team" ] }, "teamId": { "type": "string", "minLength": 1, "pattern": "\\S" }, "rarityBases": { "type": "object", "additionalProperties": false, "properties": { "COMMON": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000 }, "RARE": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000 }, "EPIC": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000 }, "LEGENDARY": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000 }, "MYTHIC": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000 } }, "minProperties": 1 }, "momentFactors": false } } ] }, "examples": { "platform": { "value": { "scope": "platform", "rarityBases": { "COMMON": 12 }, "momentFactors": { "ACTION": 1.5 } } }, "team": { "value": { "scope": "team", "teamId": "hc-sierre", "rarityBases": { "COMMON": 15, "RARE": null } } } } } } }, "responses": { "200": { "description": "Card value tables after the write", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/CardValueSettings" }, { "type": "object", "properties": { "platformRarityBases": { "required": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC" ] }, "effectiveRarityBases": { "required": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC" ] }, "momentFactors": { "required": [ "PORTRAIT", "ACTION", "MILESTONE", "GAME_WINNER" ] } } } ] } } }, "example": { "success": true, "data": { "platformRarityBases": { "COMMON": 10, "RARE": 50, "EPIC": 150, "LEGENDARY": 500, "MYTHIC": 1500 }, "teamId": null, "teamRarityBases": null, "effectiveRarityBases": { "COMMON": 10, "RARE": 50, "EPIC": 150, "LEGENDARY": 500, "MYTHIC": 1500 }, "momentFactors": { "PORTRAIT": 1, "ACTION": 1.25, "MILESTONE": 1.75, "GAME_WINNER": 2 } } } } }, "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } } }, "400": { "description": "Validation error (VALIDATION_ERROR)", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ] } } } } } }, "401": { "description": "Authentication required", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED" ] } } } } } }, "403": { "description": "Authenticated caller is neither admin nor superadmin (FORBIDDEN); club membership is insufficient.", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } }, "404": { "description": "Team not found (NOT_FOUND)", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "NOT_FOUND" ] } } } } } }, "500": { "description": "Settings read or transaction failed (INTERNAL_ERROR)", "headers": { "Cache-Control": { "description": "Personalized settings and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } } } } }, "/api/collectible-sets": { "get": { "tags": [ "Collectibles" ], "summary": "Collectible set progress", "description": "Authenticated. Sets the fan follows or favorites, sets where they own a member, and sets they have completed. Each set includes owned/total, sorted missing collectible ids, completion, and redeemable common/rare cards. pointsBalance is a non-cash set-point balance. tradeInRates and redeemCosts are the published point tables. A fan who already owns a full set is granted the cosmetic badge once on this read.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ pointsBalance, tradeInRates, redeemCosts, sets }. Epic, legendary, and mythic have trade-in rates and no redeem cost.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "pointsBalance", "tradeInRates", "redeemCosts", "sets" ], "properties": { "pointsBalance": { "type": "integer", "minimum": 0 }, "tradeInRates": { "type": "object", "description": "Points earned per extra copy. COMMON 10, RARE 25, EPIC 60, LEGENDARY 150, MYTHIC 400. Not coins.", "required": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC" ], "properties": { "COMMON": { "type": "integer" }, "RARE": { "type": "integer" }, "EPIC": { "type": "integer" }, "LEGENDARY": { "type": "integer" }, "MYTHIC": { "type": "integer" } }, "additionalProperties": false }, "redeemCosts": { "type": "object", "description": "Points a missing card costs. COMMON 50, RARE 150. Epic, legendary, and mythic are absent.", "required": [ "COMMON", "RARE" ], "properties": { "COMMON": { "type": "integer" }, "RARE": { "type": "integer" } }, "additionalProperties": false }, "sets": { "type": "array", "items": { "$ref": "#/components/schemas/CollectibleSetProgressSet" } } } } } } } } }, "401": { "description": "Authentication required (UNAUTHORIZED)" } } } }, "/api/collectible-sets/{setId}/trade-in": { "post": { "tags": [ "Collectibles" ], "summary": "Trade in duplicate collectibles for set points", "description": "Authenticated. Burns quantity extra copies of a set member for set points. Never burns the last copy, a listed or offered copy (lockedBy listing: or offer:, including a whole-row lock), or a minted/minting copy, or a pending/failed mint that already has an Engine job. A pending or failed mint with no Engine job can be burned, and that row is marked burned so it is not submitted. Points are not coins and cannot be converted. The same idempotencyKey replays the stored receipt. A reused key with a different set, card, or quantity is 409 IDEMPOTENCY_KEY_CONFLICT.", "parameters": [ { "name": "setId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collectibleId", "quantity", "idempotencyKey" ], "properties": { "collectibleId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9:_-]{8,128}$" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ alreadyRecorded, pointsDelta, pointsBalance, setId, collectibleId, quantity, ownedAfter, set, reward }. pointsDelta is positive. reward is set only when this call granted the cosmetic badge.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SetPointMutation" } } } } } }, "400": { "description": "VALIDATION_ERROR — body is not a JSON object, or the card is not in the set, or quantity / idempotencyKey is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "401": { "description": "Authentication required (UNAUTHORIZED)" }, "404": { "description": "Collectible set not found or inactive (NOT_FOUND)" }, "409": { "description": "LAST_COPY, ITEM_LOCKED, COPIES_MINTED, INSUFFICIENT_QUANTITY, or IDEMPOTENCY_KEY_CONFLICT." } } } }, "/api/collectible-sets/{setId}/redeem": { "post": { "tags": [ "Collectibles" ], "summary": "Redeem set points for a missing common or rare", "description": "Authenticated. Spends set points on one missing common or rare member of the set. The card is added to the fan's primary wallet (source set_redeem) and that wallet's default binder when one exists. Epic, legendary, and mythic cards are NOT_REDEEMABLE. The same idempotencyKey replays the stored receipt.", "parameters": [ { "name": "setId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collectibleId", "idempotencyKey" ], "properties": { "collectibleId": { "type": "string" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9:_-]{8,128}$" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ alreadyRecorded, pointsDelta, pointsBalance, setId, collectibleId, quantity, ownedAfter, set, reward }. pointsDelta is negative. set.newlyCompleted is true when this redeem finished the set.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SetPointMutation" } } } } } }, "400": { "description": "VALIDATION_ERROR for a bad body. NOT_REDEEMABLE when the card is not common or rare.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "401": { "description": "Authentication required (UNAUTHORIZED)" }, "404": { "description": "Collectible set not found or inactive (NOT_FOUND)" }, "409": { "description": "ALREADY_OWNED, INSUFFICIENT_SET_POINTS, or IDEMPOTENCY_KEY_CONFLICT." } } } }, "/api/collectibles/resolve-sports": { "post": { "tags": [ "Collectibles" ], "summary": "Resolve sport and league for collectibles", "description": "Authenticated. Body { collectibleIds: string[] } (1–100). Returns items in request order with duplicates collapsed. Unknown ids come back with sport: null and league: null rather than a 404.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collectibleIds" ], "properties": { "collectibleIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "minLength": 1 } } } } } } }, "responses": { "200": { "description": "{ success, data: { items } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "collectibleId", "sport", "league" ], "properties": { "collectibleId": { "type": "string" }, "sport": { "type": [ "string", "null" ], "description": "Sports-catalog slug (GET /api/config/sports) of the card team's league; null for unknown ids or leagueless teams." }, "league": { "type": [ "object", "null" ], "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } } } }, "400": { "description": "VALIDATION_ERROR — empty, oversized or non-string id list" }, "401": { "description": "Authentication required" }, "500": { "description": "INTERNAL_ERROR" } } } }, "/api/v1/players/search": { "get": { "tags": [ "Players" ], "summary": "Search the player directory", "description": "Authenticated typeahead over active roster players. Name contains q (case-insensitive); names that start with q come first, then alphabetical.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 64 } }, { "name": "sport", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hockey", "basketball", "soccer", "football", "baseball", "other" ] }, "description": "Only players whose team's league plays this sport." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } } ], "responses": { "200": { "description": "{ success, data: { players } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "players" ], "properties": { "players": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "teamName", "sport", "imageUrl" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "teamName": { "type": [ "string", "null" ], "description": "Linked team's name, else the player's own team text." }, "sport": { "type": [ "string", "null" ], "description": "Sports-catalog slug of the team's league." }, "imageUrl": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "description": "VALIDATION_ERROR — bad q, sport or limit" }, "401": { "description": "Authentication required" }, "500": { "description": "INTERNAL_ERROR" } } } }, "/api/admin/social/oauth": { "get": { "tags": [ "Admin" ], "operationId": "adminSocialOAuthList", "summary": "List connected social accounts (admin)", "description": "Team admin (#851 Opt A v1: X-only). teamId query accepts id or slug. Requires canManageTeam. Ciphertext never returned. Tokens encrypted at rest (AUTH_SECRET), scoped per team.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "teamId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data: { accounts: SocialAccount[] } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" } } }, "post": { "tags": [ "Admin" ], "operationId": "adminSocialOAuthConnect", "summary": "Connect social account (admin)", "description": "Team admin. Upserts one (team, platform) row; v1 accepts platform x only. accessToken stored encrypted (Encryptinator/AUTH_SECRET); audit-logged via StaffActivityLog.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId", "platform", "accessToken" ], "properties": { "teamId": { "type": "string" }, "platform": { "type": "string", "enum": [ "x" ] }, "handle": { "type": "string" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "{ success, data: { account: SocialAccount } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" } } }, "delete": { "tags": [ "Admin" ], "operationId": "adminSocialOAuthDisconnect", "summary": "Disconnect social account (admin)", "description": "Team admin. Clears ciphertext, sets disconnected; row retained for audit.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId", "platform" ], "properties": { "teamId": { "type": "string" }, "platform": { "type": "string", "enum": [ "x" ] } } } } } }, "responses": { "200": { "description": "{ success, data: { disconnected: true } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" } } } }, "/api/admin/social/posts": { "get": { "tags": [ "Admin" ], "operationId": "adminSocialPostsList", "summary": "List scheduled social posts (admin)", "description": "Team admin. Query teamId, status? (one status or comma-separated list), limit?. Newest scheduled first.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "teamId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "One status or comma-separated list. Allowed: scheduled, sending, published, failed, cancelled." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "{ success, data: { posts: SocialScheduledPost[] } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" } } }, "post": { "tags": [ "Admin" ], "operationId": "adminSocialPostsCreate", "summary": "Schedule social post (admin)", "description": "Team admin. content<=280, scheduledAt ISO-8601, mediaUrls<=10 from /media. 5-min cron publishes at scheduledAt.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId", "content", "scheduledAt" ], "properties": { "teamId": { "type": "string" }, "platform": { "type": "string", "enum": [ "x" ] }, "content": { "type": "string", "maxLength": 280 }, "scheduledAt": { "type": "string", "format": "date-time" }, "mediaUrls": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "{ success, data: { post: SocialScheduledPost } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" } } } }, "/api/admin/social/posts/{id}": { "patch": { "tags": [ "Admin" ], "operationId": "adminSocialPostReschedule", "summary": "Reschedule or cancel social post (admin)", "description": "Team admin. status cancelled cancels; else revalidates to scheduled. Only scheduled/failed editable (409 otherwise).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "teamId" ], "properties": { "teamId": { "type": "string" }, "content": { "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time" }, "mediaUrls": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "cancelled" ] } } } } } }, "responses": { "200": { "description": "{ success, data: { post: SocialScheduledPost } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" } } }, "delete": { "tags": [ "Admin" ], "operationId": "adminSocialPostCancel", "summary": "Cancel scheduled social post (admin)", "description": "Team admin. Terminal cancelled; published/sending 409. Row retained.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "teamId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ success, data: { post: SocialScheduledPost } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" } } } }, "/api/admin/card-art-batches": { "get": { "tags": [ "Admin", "Collectibles and packs" ], "summary": "List card-art batches", "description": "Team-admin list of partner card-art batches (#853), newest first. Query: teamId (id or slug), page, pageSize. Same canManageTeam gate; review tiles stay private-bucket paths.", "parameters": [ { "name": "teamId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { batches, total } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } }, "post": { "tags": [ "Admin", "Collectibles and packs" ], "summary": "Create card-art batch", "description": "Team admin creates a batch from uploaded private-bucket clips (#853). Body: { teamId, season, clips: [{ storagePath, moment: intro|celebration, videoName }] }. Clips must live under club-media///. Roster auto-match runs by initial+surname; unmatched names are flagged. Queues the batch for the Fly render worker.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "{ success, data: batch summary }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/admin/card-art-batches/{id}": { "get": { "tags": [ "Admin", "Collectibles and packs" ], "summary": "Read card-art batch", "description": "Team-admin batch detail (#853): clips, roster map, unmatched names, worker manifest + QA flags and the seed draft plan when present. Same canManageTeam gate.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: batch detail }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/admin/card-art-batches/{id}/approve": { "post": { "tags": [ "Admin", "Collectibles and packs" ], "summary": "Approve card-art batch", "description": "Team admin approves a needs_review batch (#853): validates the stored worker manifest, recomputes QA flags, finalises it and returns the collection-seed draft plan. Creates no collectibles; applying drafts and publishing stay separate, explicit actions (no-auto-publish). Empty body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { batch, seedPlan } }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" } } } }, "/api/admin/card-art-batches/{id}/requeue": { "post": { "tags": [ "Admin", "Collectibles and packs" ], "summary": "Requeue failed card-art batch", "description": "Team admin moves a failed batch back to queued for retry (#853). The failure reason stays on the row for audit; progress resets. Empty body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: batch }" }, "401": { "description": "{ success: false, error, code: UNAUTHORIZED }" }, "403": { "description": "{ success: false, error, code: FORBIDDEN }" }, "404": { "description": "{ success: false, error, code: NOT_FOUND }" }, "409": { "description": "{ success: false, error, code: CONFLICT }" } } } }, "/api/v1/engage/games/daily-pickem/slate": { "get": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Read the full UTC-day Daily Pick'em slate", "description": "All real non-demo fixtures already persisted by this API within the current UTC day, ordered by start and ID. Locked fixtures remain visible. Canonical leg IDs are pickem::; the owned session promptId may alias the same fixture. Unknown metadata and unfinished winningKey fields are omitted. No per-request vendor fetch. Served by this Next.js API under app/api/v1/engage/games/daily-pickem/; not a Rust-backend contract in this repository. Clients keep calling this API until a cutover registers the same paths and parlay error codes on the destination first.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "legs" ], "properties": { "legs": { "type": "array", "items": { "$ref": "#/components/schemas/PickemLeg" } } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } } } } }, "/api/v1/engage/games/daily-pickem/parlay": { "post": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Submit an immutable no-risk Daily Pick'em parlay", "description": "Commit the existing engine session action first. Choose two or more distinct current-slate fixtures before their authoritative lock times. The matching session fixture must retain its committed option and receives no duplicate normal reward. Correct extra legs earn snapshotted normal Rep on the selected board; all-correct bonus tiers are 10/25/50/100 and recalculate after voids. No stake or deductions. One slip per user per UTC day. Exact normalized key/payload retries replay the stored receipt, including after midnight. Team boards require existing partner-club Earn eligibility; eligibility and rewards snapshot at submission. Body maximum 64 KiB; unknown fields are rejected. Served by this Next.js API under app/api/v1/engage/games/daily-pickem/; not a Rust-backend contract in this repository. Clients keep calling this API until a cutover registers the same paths and parlay error codes on the destination first.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/PickemParlayReceipt" } }, "additionalProperties": false } } } }, "400": { "description": "INVALID_PICKS", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "403": { "description": "BOARD_NOT_ALLOWED", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "409": { "description": "LEG_LOCKED, SESSION_PICK_REQUIRED, SESSION_PICK_CONFLICT, PARLAY_EXISTS, IDEMPOTENCY_KEY_CONFLICT, GAME_DAILY_NOT_ELIGIBLE", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "413": { "description": "PAYLOAD_TOO_LARGE: request body exceeds 64 KiB", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "503": { "description": "RATE_LIMITER_UNAVAILABLE or a retryable transaction failure", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickemParlayInput" } } } } } }, "/api/v1/engage/games/daily-pickem/parlay/today": { "get": { "tags": [ "Games", "Game Engine", "Engage" ], "summary": "Read the caller's Daily Pick'em slip for the current UTC day", "description": "Returns the owned immutable slip with updated settlement state, or null. Another user cannot read the receipt. Status remains OPEN while required settlement writes are retrying. Served by this Next.js API under app/api/v1/engage/games/daily-pickem/; not a Rust-backend contract in this repository. Clients keep calling this API until a cutover registers the same paths and parlay error codes on the destination first.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "parlay" ], "properties": { "parlay": { "anyOf": [ { "$ref": "#/components/schemas/PickemParlayReceipt" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } } } } }, "/api/inventory/transfers": { "get": { "tags": [ "Collectibles and packs" ], "summary": "List this fan's inventory moves", "description": "Signed-in fan. Append-only InventoryTransfer rows where the caller is the sender or the toUserId recipient (#941). A userId query is ignored. Includes admin reversals of this fan's rows. Admin notes on those rows are returned as null. When the caller is only the recipient, the sender's fromWallet, fromBinderId, feeCash and clientVersion are null. Off with 404 FEATURE_DISABLED unless INVENTORY_TRANSFERS_ENABLED is true. Does not move inventory.", "operationId": "listFanInventoryTransfers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "itemRef", "in": "query", "required": false, "description": "Only rows for this item ref (#1029). Trimmed; blank is ignored. With collectibleId, a row matches either one. Never widens the caller scope.", "schema": { "type": "string" } }, { "name": "collectibleId", "in": "query", "required": false, "description": "Only rows for this collectible, including minted copies whose itemRef differs (#1029). Trimmed; blank is ignored. With itemRef, a row matches either one. Never widens the caller scope.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Page of this fan's ledger rows", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "items", "pagination" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "required": [ "page", "pageSize", "total", "totalPages" ], "additionalProperties": false, "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } } } }, "401": { "description": "UNAUTHORIZED" }, "404": { "description": "FEATURE_DISABLED — INVENTORY_TRANSFERS_ENABLED is off" }, "500": { "description": "INTERNAL_ERROR" } } }, "post": { "tags": [ "Collectibles and packs" ], "summary": "Move packs and cards between this fan's wallets", "description": "Signed-in fan. Both wallets must be linked to the caller and different. Items are pack_unopened, pack_opened, or card (quantity or serial), at most 50, all-or-nothing. transferId is a UUID; a replay returns the stored lines and skips PIN verification. When requirePinForInventoryMove is enabled, a 6-digit pin verifies the source wallet before a non-replay move; the PIN is not stored or included in replay matching. Opened packs move independently of their cards. Writes through InventoryCustody and the InventoryTransfer ledger (#940, #941). Off with 404 FEATURE_DISABLED unless INVENTORY_TRANSFERS_ENABLED is true. Database custody settles immediately. On-chain custody is not implemented and returns 503 CUSTODY_UNAVAILABLE.", "operationId": "transferFanInventory", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transferId", "fromWallet", "toWallet", "items" ], "additionalProperties": false, "properties": { "transferId": { "type": "string", "format": "uuid" }, "fromWallet": { "type": "string" }, "toWallet": { "type": "string" }, "toBinderId": { "type": "string" }, "pin": { "type": "string", "pattern": "^\\d{6}$", "description": "Six-digit source-wallet PIN; required only when requirePinForInventoryMove is enabled." }, "clientVersion": { "type": "string" }, "items": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "type", "ref" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "pack_unopened", "pack_opened", "card" ] }, "ref": { "type": "string" }, "qty": { "type": "integer", "minimum": 1 }, "serial": { "type": "string" }, "fromBinderId": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Settled move. replayed is true when transferId was already stored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "transferId", "status", "replayed", "results", "counts" ], "additionalProperties": false, "properties": { "transferId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "settled" ] }, "replayed": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "counts": { "type": "object", "required": [ "packs", "cards", "items" ], "additionalProperties": false, "properties": { "packs": { "type": "integer" }, "cards": { "type": "integer" }, "items": { "type": "integer" } } } } } } } } } }, "400": { "description": "INVALID_PIN (wrong wallet PIN), VALIDATION_ERROR, SAME_WALLET, TOO_MANY_ITEMS, or PACK_PAYMENT_PENDING. A required wallet PIN that needs reset includes requiresPinReset: true." }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "WALLET_NOT_LINKED — a wallet is not linked to this fan; PIN_REQUIRED — enter the source wallet PIN" }, "404": { "description": "FEATURE_DISABLED or NOT_FOUND" }, "409": { "description": "ITEM_LISTED, ITEM_OPENING, ITEM_PENDING_SORT, ITEM_NOT_IN_WALLET, IDEMPOTENCY_KEY_CONFLICT, PACK_ALREADY_OPENED, ITEM_STATE, INSUFFICIENT_QUANTITY, or WALLET_MISMATCH" }, "429": { "description": "RATE_LIMITED — PIN verification quota or INVENTORY_TRANSFER_RATELIMIT_ENABLED transfer quota" }, "500": { "description": "INTERNAL_ERROR" }, "503": { "description": "CUSTODY_UNAVAILABLE — on-chain custody is not implemented; RATE_LIMITER_UNAVAILABLE — fail-closed PIN limiter" } } } }, "/api/admin/market-abuse": { "get": { "tags": [ "Admin" ], "summary": "Wash-style marketplace report", "description": "Platform admin. Ledger heuristics only (#942): ping-pong pairs, fast flips, and sub-minimum sales. Does not block a trade. Device and payment fingerprints are not stored.", "operationId": "adminMarketAbuse", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "windowDays", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 30 } } ], "responses": { "200": { "description": "{ success, data: { windowDays, pingPong, fastFlips, subMinimum } }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" }, "500": { "description": "INTERNAL_ERROR" } } } }, "/api/admin/ops/search": { "get": { "tags": [ "Admin" ], "summary": "Permission-scoped Ops hub search", "description": "Searches fans and moderation reports the caller may use. `fans` needs platform admin (admin or superadmin, the GET /api/admin/users gate) and matches email, name or handle case-insensitively. `reports` needs moderator (moderator, admin or superadmin) and matches a report id prefix or a case-insensitive reason substring. Moderators and ordinary admins never match escalated reports; only superadmins do. A group the caller may not use is omitted rather than returned empty, so a caller with neither tool gets `{}`. Each group is capped at `limit`, newest first; there is no pagination. Reporter and target identities, report details and approval reasons are never returned. Limited to 30 requests per 60 seconds per caller; a limiter outage fails closed. Every response is `Cache-Control: private, no-store`.", "operationId": "adminOpsSearch", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search text, trimmed; 1 to 100 characters after trimming. `%`, `_` and `\\` are matched literally, not as wildcards.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum items per group. Values above 20 are rejected, not clamped.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } ], "responses": { "200": { "description": "Authorized groups only. `{}` when the caller is neither admin nor moderator.", "headers": { "Cache-Control": { "description": "Personalized results must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "fans": { "type": "array", "maxItems": 20, "description": "Present only for platform admins.", "items": { "type": "object", "required": [ "id", "handle", "name", "email" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "handle": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } } }, "reports": { "type": "array", "maxItems": 20, "description": "Present only for moderators and above.", "items": { "type": "object", "required": [ "id", "status", "createdAt", "reason" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "ESCALATED", "REVIEWED", "RESOLVED", "DISMISSED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } } } } } } } }, "examples": { "admin": { "summary": "Test fixture: platform admin", "value": { "success": true, "data": { "fans": [ { "id": "user_1", "handle": "alex", "name": "Alex Example", "email": "alex@example.com" } ], "reports": [ { "id": "rep_1", "status": "PENDING", "createdAt": "2026-11-01T12:00:00.000Z", "reason": "spam" } ] } } }, "clubOnly": { "summary": "Test fixture: caller with neither tool", "value": { "success": true, "data": {} } } } } } }, "400": { "description": "VALIDATION_ERROR: q missing, blank or longer than 100 characters, or limit not an integer from 1 to 20.", "headers": { "Cache-Control": { "description": "Handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } } }, "401": { "description": "UNAUTHORIZED", "headers": { "Cache-Control": { "description": "Handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } } }, "429": { "description": "RATE_LIMITED: more than 30 requests in 60 seconds.", "headers": { "Cache-Control": { "description": "Handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "Cache-Control": { "description": "Handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } } }, "503": { "description": "RATE_LIMITER_UNAVAILABLE: the limiter store is unreachable, so the request fails closed.", "headers": { "Cache-Control": { "description": "Handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } } } } } }, "/api/admin/inventory-transfers": { "get": { "tags": [ "Admin" ], "summary": "List inventory move ledger rows", "description": "Platform admin. Append-only InventoryTransfer rows (#940). transferId is unique per fan, so pass userId to scope the page. Does not move inventory.", "operationId": "adminListInventoryTransfers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "itemRef", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Page of ledger rows", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "items", "pagination" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "required": [ "page", "pageSize", "total", "totalPages" ], "additionalProperties": false, "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } } } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "403": { "description": "FORBIDDEN — caller is not a platform admin", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } } } }, "post": { "tags": [ "Admin" ], "summary": "Reverse one inventory move", "description": "Platform admin. Appends a second InventoryTransfer row with reason admin_reverse and restores the pack or card. The original row is not updated. userId is required because transferId is unique per fan, not globally. Does not settle marketplace trades (#942) and is not the fan transfer endpoint (#941).", "operationId": "adminReverseInventoryTransfer", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transferId", "userId" ], "additionalProperties": false, "properties": { "transferId": { "type": "string" }, "userId": { "type": "string" }, "note": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Original row plus the new reversal row", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "additionalProperties": false, "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "original", "reversal" ], "additionalProperties": false, "properties": { "original": { "type": "object", "additionalProperties": true }, "reversal": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "VALIDATION_ERROR", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "403": { "description": "FORBIDDEN, or WALLET_NOT_LINKED when a wallet on the move is not linked", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "404": { "description": "TRANSFER_NOT_FOUND, or NOT_FOUND when the item or binder is missing", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "409": { "description": "TRANSFER_ALREADY_REVERSED, INSUFFICIENT_QUANTITY, LISTING_PINNED, PACK_ALREADY_OPENED, ITEM_STATE, WALLET_MISMATCH, or CONFLICT when the transfer is not settled", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "500": { "description": "INTERNAL_ERROR", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } }, "503": { "description": "CUSTODY_UNAVAILABLE", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" } }, "additionalProperties": false } } } } } } }, "/api/events/{gameId}/chat/promoted": { "get": { "tags": [ "Events" ], "summary": "Promoted chat moments", "description": "Ranked game-thread moments for the feed chat-promotion skin. Each moment carries per-emoji reaction counts (with `mine` for the signed-in viewer), `topReply` (most-reacted visible reply; `isPlayer` marks replies from fixture-club TeamAdmins — the official voice), `relTime`, `gameLabel`, `scoreChip`, and `spiking`. Viewer mute/block filters apply; anonymous-safe (reactions lose `mine`).", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/v1/events/{gameId}": { "get": { "tags": [ "Events" ], "summary": "Get v1 event bundle", "description": "Consolidated game-detail payload { version: 1, game, plays, playsTruncated, stats, lineup, ratings, onlineCount }. `game` carries the same `realtime` pointer as GET /api/events/{gameId}. `plays` walks the provider feed (<=5x100; `playsTruncated` flags saturation). `lineup` reuses the ratings view (getRatingsMeta seeds vendor-final slots on read); `ratings`/`onlineCount` degrade to null/0. Optional auth — `ratings.myRatings` populates when signed in. Weak-ETag cached; `serverTime`/`periodEndsAt` omitted from the hash so a clock tick still 304s.", "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data }" } } } }, "/api/teams/{id}/season-state": { "get": { "tags": [ "Teams" ], "summary": "Get team season state", "description": "Public. The off-season hub gate for one team and nothing else: { teamId, teamSlug, seasonState: { state, hubEnabled } }. Same derivation as team.seasonState on GET /api/teams/{id}, for clients that only need the gate. `state` comes from the league's persisted hockey calendar window (LeagueSeasonWindow) and is compared in whole UTC days with endDate inclusive; a manual stateOverride or hubEnabled on that window wins over the dates. A team whose league has no window falls back to the default hockey calendar, but only for sport hockey — any other sport, and a team with no league, resolves to in_season with the hub closed. Archived and unknown refs 404; a blank ref is 400.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id or slug.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "{ success, data: { teamId, teamSlug, seasonState } }" }, "400": { "description": "VALIDATION_ERROR" }, "404": { "description": "Team not found" } } } }, "/api/admin/leagues/{leagueId}/season-windows": { "get": { "tags": [ "Admin" ], "summary": "List league season windows", "description": "Platform admin only. Every persisted hockey calendar window for a league, newest season first: { windows: [{ id, leagueId, seasonYear, startDate, endDate, preseasonStartDate, stateOverride, hubEnabled, createdAt, updatedAt }] }. These rows drive seasonState on team detail (#999). Nullable stateOverride / hubEnabled mean the phase and hub switch are derived from the dates. 404 for an unknown league ref, so an empty list means no calendar is configured yet.", "parameters": [ { "name": "leagueId", "in": "path", "required": true, "description": "League id or slug.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { windows } }" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN — platform admin only" }, "404": { "description": "NOT_FOUND — unknown league" } } }, "put": { "tags": [ "Admin" ], "summary": "Upsert a league season window", "description": "Platform admin only. Creates or replaces the window for one season year, idempotent on (leagueId, seasonYear). Body: { seasonYear, startDate, endDate, preseasonStartDate?, stateOverride?, hubEnabled? }. Dates are ISO-8601; endDate must not precede startDate and preseasonStartDate must not follow startDate. stateOverride (in_season | off_season | preseason | null) opens or holds the off-season hub outside the date math; hubEnabled (boolean | null) pins the hub switch on its own. Both nullable — null derives. 400 is returned only for an invalid body; a persistence failure is 500.", "parameters": [ { "name": "leagueId", "in": "path", "required": true, "description": "League id or slug.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "seasonYear", "startDate", "endDate" ], "properties": { "seasonYear": { "type": "integer", "minimum": 1900, "maximum": 3000, "description": "Season label year (2026 = the 2026-27 season)." }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time", "description": "Last day of the season, inclusive." }, "preseasonStartDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Training camp opener. Null means no preseason phase." }, "stateOverride": { "type": "string", "enum": [ "in_season", "off_season", "preseason" ], "nullable": true }, "hubEnabled": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "{ success, data: { window } }" }, "400": { "description": "VALIDATION_ERROR — invalid body" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN — platform admin only" }, "404": { "description": "League not found" }, "500": { "description": "INTERNAL_ERROR — the write could not be persisted" } } } }, "/api/mobile/changelog": { "get": { "tags": [ "Mobile" ], "operationId": "getMobileChangelog", "summary": "List published changelog entries (What's New feed)", "description": "Unauthenticated. `data` is `{ entries }` — published entries only, newest first by `publishedAt`. A draft is never served. Optional filters: `platform` (ios|android|all) keeps platform-`null`/`all` entries plus exact matches; `version` requires `X.Y.Z`-style input; `updateId` returns the best-matching entry — an exact `updateIds` array match first, otherwise the `STORE_RELEASE` entry matching `?version` + `?platform`. Responds 304 with no body when `If-None-Match` matches the served `ETag` (weak, over the whole envelope). `Cache-Control: public, s-maxage=300, stale-while-revalidate=3600`. Authored locales (#1044): Accept-Language resolves en/fr-CH/it-IT. Only reviewed published JSON snapshots are served, otherwise English; never machine translation. Every 200/304 sets Vary: Accept-Language and actual Content-Language (en on fallback/empty; en, on mixed changelog feeds). English bytes/ETags stay legacy; non-English ETags include negotiated locale even on fallback. Cache by negotiated locale. ApprovedCopy version is locale-owned, changelog app version remains base-owned; variant updatedAt is its publish time. Locale deletion/recreation resets its publish counter. Missing new locale table during rollout falls back; unrelated failures return 500.", "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ios", "android", "all" ] } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+" } }, { "name": "updateId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Shared language negotiation; missing/unsupported headers resolve to en." }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Validator for this negotiated locale. Wildcard matches any current representation." } ], "security": [], "responses": { "200": { "description": "{ success, data: { entries } }", "headers": { "Content-Language": { "schema": { "type": "string" }, "description": "Actual served languages: en, fr-CH, it-IT, or mixed en, fr-CH / en, it-IT" }, "Vary": { "schema": { "type": "string" }, "description": "Accept-Language" }, "ETag": { "schema": { "type": "string" }, "description": "Locale-aware weak validator; English legacy hash unchanged" }, "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300, stale-while-revalidate=3600" } } }, "304": { "description": "Not modified — `If-None-Match` matched the current `ETag`. No body.", "headers": { "Content-Language": { "schema": { "type": "string" }, "description": "Actual served languages: en, fr-CH, it-IT, or mixed en, fr-CH / en, it-IT" }, "Vary": { "schema": { "type": "string" }, "description": "Accept-Language" }, "ETag": { "schema": { "type": "string" }, "description": "Locale-aware weak validator; English legacy hash unchanged" }, "Cache-Control": { "schema": { "type": "string" }, "description": "public, s-maxage=300, stale-while-revalidate=3600" } } }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "500": { "description": "{ success: false, error, code: \"INTERNAL_ERROR\" }" } } } }, "/api/admin/changelog": { "get": { "tags": [ "Admin" ], "operationId": "listAdminChangelog", "summary": "List changelog entries", "description": "Platform moderator/admin only (no team scope). `{ entries: AdminChangelogEntry[] }`, most recently edited first (max 100): each entry carries its full fields plus `status`, `publishedAt`, `publishedBy`, `draftUpdatedBy`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: { entries } }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" } } }, "post": { "tags": [ "Admin" ], "operationId": "upsertAdminChangelogEntry", "summary": "Create or update a changelog entry by slug", "description": "Platform moderator/admin only. `slug` plus any subset of entry fields. A complete body (kind, version, dateLabel, title, sections) creates the slug when absent — 201 on create, 200 on re-save; a partial body updates an existing entry only (VALIDATION_ERROR when absent). `tags` accepts the client wire shape — plain labels or `{label, platform?}` objects; `sections`/`bullets` are validated the same way. A write never touches `status`/`publishedAt` — publish separately.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 }, "kind": { "type": "string", "enum": [ "STORE_RELEASE", "OTA_UPDATE" ], "description": "STORE_RELEASE ships no updateIds; OTA_UPDATE requires at least one on create (merged pair is checked on partial writes)." }, "version": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$", "description": "Client-facing app/build version, e.g. `1.31.0`." }, "updateIds": { "type": "array", "maxItems": 40, "items": { "type": "string", "format": "uuid" }, "description": "Expo/EAS update ids this entry covers (OTA_UPDATE only)." }, "dateLabel": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Verbatim display label, e.g. `October 2026` — not a timestamp." }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "titlePlatform": { "anyOf": [ { "type": "string", "enum": [ "ios", "android", "all" ] }, { "type": "null" } ], "description": "Audience override for the heading line." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "ios", "android", "all" ] }, { "type": "null" } ], "description": "Audience filter for the whole entry; `null`/`all` = every client." }, "tags": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] } } } ] } }, "sections": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "object", "properties": { "heading": { "type": "string", "minLength": 1, "maxLength": 160 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] }, "bullets": { "type": "array", "maxItems": 60, "items": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] } } } ] } } } } } } } } } }, "responses": { "200": { "description": "{ success, data: AdminChangelogEntry } — an existing entry was updated." }, "201": { "description": "{ success, data: AdminChangelogEntry } — the entry was created." }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" } } } }, "/api/admin/changelog/{slug}": { "get": { "tags": [ "Admin" ], "operationId": "getAdminChangelogEntry", "summary": "Get one changelog entry", "description": "Platform moderator/admin only. The full row including draft fields and publish stamps.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "Changelog slug derived from the version, e.g. `1-31-0`." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: AdminChangelogEntry }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" }, "404": { "description": "{ success: false, error, code: \"NOT_FOUND\" }" } } }, "put": { "tags": [ "Admin" ], "operationId": "saveAdminChangelogEntry", "summary": "Partially update a changelog entry", "description": "Platform moderator/admin only. Partial write: omitted fields keep their stored value (passing `null` clears `platform`/`titlePlatform`). Requires at least one field. Draft rows never reach `GET /api/mobile/changelog` — only `POST .../publish` exposes an entry — but saving an already-published row takes effect on the next read (single-row status-flip model). `PATCH` is an alias of `PUT`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "Changelog slug derived from the version, e.g. `1-31-0`." } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "STORE_RELEASE", "OTA_UPDATE" ], "description": "STORE_RELEASE ships no updateIds; OTA_UPDATE requires at least one on create (merged pair is checked on partial writes)." }, "version": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$", "description": "Client-facing app/build version, e.g. `1.31.0`." }, "updateIds": { "type": "array", "maxItems": 40, "items": { "type": "string", "format": "uuid" }, "description": "Expo/EAS update ids this entry covers (OTA_UPDATE only)." }, "dateLabel": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Verbatim display label, e.g. `October 2026` — not a timestamp." }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "titlePlatform": { "anyOf": [ { "type": "string", "enum": [ "ios", "android", "all" ] }, { "type": "null" } ], "description": "Audience override for the heading line." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "ios", "android", "all" ] }, { "type": "null" } ], "description": "Audience filter for the whole entry; `null`/`all` = every client." }, "tags": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] } } } ] } }, "sections": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "object", "properties": { "heading": { "type": "string", "minLength": 1, "maxLength": 160 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] }, "bullets": { "type": "array", "maxItems": 60, "items": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] } } } ] } } } } } } } } } }, "responses": { "200": { "description": "{ success, data: AdminChangelogEntry }" }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" } } }, "patch": { "tags": [ "Admin" ], "operationId": "patchAdminChangelogEntry", "summary": "Alias of PUT — partially update a changelog entry", "description": "Same handler and body as `PUT /api/admin/changelog/{slug}`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "Changelog slug derived from the version, e.g. `1-31-0`." } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "STORE_RELEASE", "OTA_UPDATE" ], "description": "STORE_RELEASE ships no updateIds; OTA_UPDATE requires at least one on create (merged pair is checked on partial writes)." }, "version": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$", "description": "Client-facing app/build version, e.g. `1.31.0`." }, "updateIds": { "type": "array", "maxItems": 40, "items": { "type": "string", "format": "uuid" }, "description": "Expo/EAS update ids this entry covers (OTA_UPDATE only)." }, "dateLabel": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Verbatim display label, e.g. `October 2026` — not a timestamp." }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "titlePlatform": { "anyOf": [ { "type": "string", "enum": [ "ios", "android", "all" ] }, { "type": "null" } ], "description": "Audience override for the heading line." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "ios", "android", "all" ] }, { "type": "null" } ], "description": "Audience filter for the whole entry; `null`/`all` = every client." }, "tags": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] } } } ] } }, "sections": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "object", "properties": { "heading": { "type": "string", "minLength": 1, "maxLength": 160 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] }, "bullets": { "type": "array", "maxItems": 60, "items": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] } } } ] } } } } } } } } } }, "responses": { "200": { "description": "{ success, data: AdminChangelogEntry }" }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" } } } }, "/api/admin/changelog/{slug}/publish": { "post": { "tags": [ "Admin" ], "operationId": "publishAdminChangelogEntry", "summary": "Publish a changelog entry", "description": "Platform moderator/admin only. Flips `status` to PUBLISHED and stamps `publishedAt`/`publishedBy` under a row lock — which is what changes the public `GET /api/mobile/changelog` payload and its `ETag`. Refused with VALIDATION_ERROR when the title is blank; 404 when the slug does not exist.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "Changelog slug derived from the version, e.g. `1-31-0`." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "{ success, data: AdminChangelogEntry }" }, "400": { "description": "{ success: false, error, code: \"VALIDATION_ERROR\" }" }, "401": { "description": "Not authenticated" }, "403": { "description": "{ success: false, error, code: \"FORBIDDEN\" }" }, "404": { "description": "{ success: false, error, code: \"NOT_FOUND\" }" } } } }, "/api/admin/ops/counts": { "get": { "tags": [ "Admin" ], "summary": "Permission-scoped Ops hub counts", "description": "Single authenticated aggregate for the native Ops hub (d-sports-engage-native#1238) so tiles do not waterfall the live, reports and submissions endpoints. data contains only the groups the caller may see: live, submissions and team require canAccessTeam on the resolved team; reports requires isModerator and mirrors the reports list visibility (non-superadmin moderators count only escalatedToSuper: false rows; superadmins count pending and escalated rows). Unauthorized groups are omitted, never zeroed; a caller allowed none still receives 200 { success: true, data: {} }. Optional teamId accepts a Team id or slug (1-128 chars trimmed); a supplied ref that resolves to nothing is 400 VALIDATION_ERROR. submissions.awaiting counts only the two human-review statuses preview_ready and pending_platform_review for the team. A live-read failure is 500, never reported as active: false. Per-user rate limit admin.ops.counts 60/60s fails closed (429 RATE_LIMITED with Retry-After; 500 when the limiter store is down). Every response, including errors, is Cache-Control: private, no-store.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Team id or slug scoping the live, submissions and team groups. Omitted returns only globally visible groups (reports for moderators)." } ], "responses": { "200": { "description": "The counts the caller is authorized to see; may be an empty object.", "headers": { "Cache-Control": { "description": "Personalized counts and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "live": { "type": "object", "required": [ "active", "sessionId" ], "properties": { "active": { "type": "boolean" }, "sessionId": { "type": [ "string", "null" ] } } }, "reports": { "type": "object", "required": [ "pending" ], "properties": { "pending": { "type": "integer" } } }, "submissions": { "type": "object", "required": [ "awaiting" ], "properties": { "awaiting": { "type": "integer" } } }, "team": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } }, "examples": { "staffWithTeam": { "summary": "Moderator with team access", "value": { "success": true, "data": { "live": { "active": true, "sessionId": "lgs_123" }, "reports": { "pending": 4 }, "submissions": { "awaiting": 2 }, "team": { "id": "team_abc", "name": "Example FC" } } } }, "clubEditor": { "summary": "Club editor (no moderator role) — reports omitted", "value": { "success": true, "data": { "live": { "active": false, "sessionId": null }, "submissions": { "awaiting": 1 }, "team": { "id": "team_abc", "name": "Example FC" } } } }, "noPermittedGroups": { "summary": "Authenticated fan allowed nothing", "value": { "success": true, "data": {} } } } } } }, "400": { "description": "Invalid teamId (blank or over 128 chars) or a supplied ref that resolves to no team (VALIDATION_ERROR).", "headers": { "Cache-Control": { "description": "Personalized counts and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ] } } } } } }, "401": { "description": "Authentication required (UNAUTHORIZED).", "headers": { "Cache-Control": { "description": "Personalized counts and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED" ] } } } } } }, "429": { "description": "Per-user rate limit exceeded (RATE_LIMITED, admin.ops.counts 60/60s).", "headers": { "Cache-Control": { "description": "Personalized counts and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } }, "Retry-After": { "description": "Seconds until the current fixed window resets.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } }, "500": { "description": "Live helper, count query or rate-limiter storage failure (INTERNAL_ERROR); the limiter fails closed.", "headers": { "Cache-Control": { "description": "Personalized counts and handled errors must not be cached.", "schema": { "type": "string", "enum": [ "private, no-store" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } } } } }, "/api/v1/engage/app-open": { "get": { "tags": [ "Engage" ], "summary": "Everything the app reads on open, in one request", "description": "User, wallets + activeWalletAddress, packs, openedPacks, unread notification count, D-Sports Cash and daily quest summary. Each section is { ok: true, data } or { ok: false, error, code }; one failing section does not fail the others.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Scope the pack sections to this wallet; ignored unless the caller owns it." }, "required": false, "description": "Scope the pack sections to this wallet; ignored unless the caller owns it.", "name": "walletAddress", "in": "query" } ], "responses": { "200": { "description": "{ success, data: AppOpenData }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppOpenSuccess" } } } }, "400": { "description": "NUL byte in the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppOpenError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppOpenError" } } } }, "500": { "description": "Failed to load app-open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppOpenError" } } } } } } }, "/api/admin/submissions": { "get": { "operationId": "listSubmissions", "summary": "List submissions for a team", "tags": [ "Submissions" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionListSuccess" } } } }, "400": { "description": "Missing teamId or invalid status filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "teamId", "in": "query", "required": true, "description": "Team ID or slug.", "schema": { "type": "string", "minLength": 1 } }, { "name": "status", "in": "query", "description": "Filter by request status. An invalid nonempty status returns 400.", "schema": { "type": "string", "enum": [ "draft", "queued", "rendering", "preview_ready", "changes_requested", "pending_platform_review", "approved", "publishing", "published", "unpublished", "render_failed", "cancelled", "expired" ] } }, { "name": "page", "in": "query", "description": "Defaults to 1; values below 1 are clamped to 1.", "schema": { "type": "number", "default": 1 } }, { "name": "pageSize", "in": "query", "description": "Defaults to 20; clamped to 1–50.", "schema": { "type": "number", "default": 20 } } ] }, "post": { "operationId": "createSubmission", "summary": "Create a draft submission", "tags": [ "Submissions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubmissionBody" } } } }, "responses": { "200": { "description": "Existing submission returned with its current status for an idempotent replay, including after publication. Cancelled, expired, and unpublished submissions release the key; reuse then creates a new draft (201) if creation succeeds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubmissionSuccess" } } } }, "201": { "description": "New draft created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubmissionSuccess" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/submissions/{id}": { "get": { "operationId": "getSubmission", "summary": "Get a submission by id", "tags": [ "Submissions" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsSuccessEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "operationId": "updateSubmissionDraftTitle", "summary": "Update the title of a draft submission", "tags": [ "Submissions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubmissionDraftBody" } } } }, "responses": { "200": { "description": "Saved draft title", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubmissionDraftSuccess" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "409": { "description": "Submission is no longer editable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Submission ID or team-scoped slug." }, { "name": "teamId", "in": "query", "schema": { "type": "string" }, "description": "Team ID or slug to disambiguate a submission slug." } ] }, "/api/admin/submissions/templates": { "get": { "operationId": "listSubmissionTemplates", "summary": "List available render templates", "tags": [ "Submissions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Team id or slug." }, "required": true, "description": "Team id or slug.", "name": "teamId", "in": "query" }, { "schema": { "type": "string", "description": "Restrict the returned content type." }, "required": false, "description": "Restrict the returned content type.", "name": "contentType", "in": "query" }, { "schema": { "type": "string", "enum": [ "latest" ], "description": "One latest compatible version per key. Default returns all eligible active versions." }, "required": false, "description": "One latest compatible version per key. Default returns all eligible active versions.", "name": "selection", "in": "query" }, { "schema": { "type": "string", "enum": [ "pack", "collectible", "team_default" ], "description": "Target context for the latest selection. A pack or collectible requires targetRef." }, "required": false, "description": "Target context for the latest selection. A pack or collectible requires targetRef.", "name": "targetKind", "in": "query" }, { "schema": { "type": "string", "description": "Team-scoped pack or collectible id or slug." }, "required": false, "description": "Team-scoped pack or collectible id or slug.", "name": "targetRef", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Allows designs that require a transparent source for a collectible target." }, "required": false, "description": "Allows designs that require a transparent source for a collectible target.", "name": "sourceHasTransparency", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionTemplateListSuccess" } } } }, "400": { "description": "Invalid template selection or target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionsErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/admin/collectibles/{id}/render-spin": { "post": { "tags": [ "Admin" ], "summary": "Queue a render from saved collectibles artwork", "description": "Team-authorized saved-artwork render. Returns 202 for a new request or 200 for idempotent reuse. A changed expected template version returns 409.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expectedTemplateVersion", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": false, "description": "Optional JSON body, at most 1 KiB. Omit the body to use the default title.", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Trimmed operator title." } } } } } }, "responses": { "200": { "description": "Existing request" }, "202": { "description": "Queued" }, "400": { "description": "Invalid body, title or version" }, "401": { "description": "Unauthorized" }, "403": { "description": "Target missing or caller not authorized to manage it." }, "404": { "description": "Render template not found or inactive." }, "409": { "description": "Template or target conflict" }, "413": { "description": "Body exceeds 1 KiB" }, "429": { "description": "Rate limited" } } } }, "/api/admin/packs/{id}/render-opening": { "post": { "tags": [ "Admin" ], "summary": "Queue a render from saved packs artwork", "description": "Team-authorized saved-artwork render. Returns 202 for a new request or 200 for idempotent reuse. A changed expected template version returns 409.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expectedTemplateVersion", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": false, "description": "Optional JSON body, at most 1 KiB. Omit the body to use the default title.", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Trimmed operator title." } } } } } }, "responses": { "200": { "description": "Existing request" }, "202": { "description": "Queued" }, "400": { "description": "Invalid body, title or version" }, "401": { "description": "Unauthorized" }, "403": { "description": "Target missing or caller not authorized to manage it." }, "404": { "description": "Render template not found or inactive." }, "409": { "description": "Template or target conflict" }, "413": { "description": "Body exceeds 1 KiB" }, "429": { "description": "Rate limited" } } } }, "/api/v1/passes/apple-wallet": { "post": { "tags": [ "Passes", "Engage" ], "summary": "Issue a signed Apple Wallet pass", "description": "Authenticated. Issues a signed Apple Wallet .pkpass for the caller (pass type pass.com.dsports.wallet). passKind is fan_id (default), club_membership (teamId required; only for an Engage partner club the caller has joined, else 403) or arena_event (gameId and/or teamId). format binary (default) returns application/vnd.apple.pkpass bytes as an attachment; format base64 returns { success, data: { passTypeIdentifier, serialNumber, passKind, contentType, filename, pkpassBase64 } } for PKAddPassesViewController. Both responses send Cache-Control: no-store. The body is capped at 4 KB. Returns 503 CONFIGURATION_ERROR until the pass signing certificates are configured on the server.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "passKind": { "type": "string", "enum": [ "fan_id", "club_membership", "arena_event" ], "default": "fan_id" }, "teamId": { "type": "string", "minLength": 1, "maxLength": 128 }, "gameId": { "type": "string", "minLength": 1, "maxLength": 128 }, "format": { "type": "string", "enum": [ "binary", "base64" ], "default": "binary" } }, "if": { "properties": { "passKind": { "const": "club_membership" } }, "required": [ "passKind" ] }, "then": { "required": [ "teamId" ] } } } } }, "responses": { "200": { "description": "Signed pass: application/vnd.apple.pkpass bytes (format binary) or { success, data: { pkpassBase64, ... } } (format base64)", "content": { "application/vnd.apple.pkpass": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/AppleWalletPassBase64Success" } } } }, "400": { "description": "VALIDATION_ERROR (invalid JSON, unknown field, or teamId missing for club_membership)" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN (club_membership pass for a non-partner club, or a partner club the caller has not joined)" }, "404": { "description": "NOT_FOUND (team or game not found)" }, "413": { "description": "PAYLOAD_TOO_LARGE (body over 4 KB)" }, "503": { "description": "CONFIGURATION_ERROR (pass signing not configured)" } } } }, "/api/v1/passes/google-wallet": { "post": { "tags": [ "Passes", "Engage" ], "summary": "Issue a signed Google Wallet pass", "description": "Authenticated. Returns a signed savetowallet JWT and Google Wallet Save URL for the caller. Omit the body or passKind for a fan ID. Only Engage partner clubs the caller has joined qualify for club_membership. arena_event uses the game, the team, or a general pass when neither is supplied; signing does not perform arena check-in. The body is capped at 4 KiB.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "passKind": { "type": "string", "enum": [ "fan_id", "club_membership", "arena_event" ], "default": "fan_id" }, "teamId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "\\S", "description": "Team ID or slug; trimmed before validation. Required for club_membership." }, "gameId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "\\S", "description": "Game event ID; trimmed before validation." } }, "if": { "required": [ "passKind" ], "properties": { "passKind": { "const": "club_membership" } } }, "then": { "required": [ "teamId" ] } } } } }, "responses": { "200": { "description": "Signed Google Wallet pass details", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleWalletPassSuccess" } } } }, "400": { "description": "VALIDATION_ERROR (invalid JSON or fields, or club_membership without teamId)" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN (not a member of the requested Engage partner club)" }, "404": { "description": "NOT_FOUND (team or game not found) or USER_NOT_PROVISIONED" }, "413": { "description": "PAYLOAD_TOO_LARGE (body exceeds 4 KiB)" }, "500": { "description": "Unexpected error issuing the pass" }, "503": { "description": "CONFIGURATION_ERROR (missing or invalid Google Wallet signing configuration)" } } } }, "/api/v1/widgets/token": { "post": { "tags": [ "Engage" ], "summary": "Issue a scoped, revocable widget bearer token", "description": "Issues an opaque `wgt_` bearer token scoped to `widgets:snapshot:read`. The 201 response returns it once; the API stores only a SHA-256 hash. Issuing again replaces the token for the same user and device. The expiry slides with successful use and is 90 days from issuance or the latest recorded use. The JSON body is capped at 4 KiB.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "deviceId", "platform" ], "properties": { "deviceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Per-install client identifier. After trimming, it must be 1–128 characters with no whitespace." }, "platform": { "type": "string", "enum": [ "android", "ios" ] } } } } } }, "responses": { "201": { "description": "Widget token issued", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetTokenIssueSuccess" } } } }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "413": { "description": "PAYLOAD_TOO_LARGE" }, "429": { "description": "RATE_LIMITED (20 token issuance requests per hour per user)" }, "503": { "description": "RATE_LIMITER_UNAVAILABLE" } } }, "delete": { "tags": [ "Engage" ], "summary": "Revoke a widget bearer token", "description": "Revokes the presented widget bearer, or revokes the signed-in Clerk user’s tokens for the given `deviceId`. With Clerk, use the query parameter or, if absent or empty, the JSON body (4 KiB maximum). A successful response may report zero matching tokens.", "security": [ { "bearerAuth": [] }, { "widgetBearerAuth": [] } ], "parameters": [ { "name": "deviceId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Device identifier to revoke when authenticating with a Clerk session." } ], "responses": { "200": { "description": "Widget token(s) revoked", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetTokenRevokeSuccess" } } } }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "413": { "description": "PAYLOAD_TOO_LARGE (Clerk-authenticated JSON request)" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "deviceId" ], "properties": { "deviceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Per-install client identifier. After trimming, it must be 1–128 characters with no whitespace." } } } } } } } }, "/api/admin/users/{userId}/widget-tokens": { "get": { "tags": [ "Admin" ], "summary": "List a user's widget tokens (admin)", "description": "Requires a Clerk session with a platform admin role. Returns widget token metadata (`id`, `deviceId`, `platform`, `scopes`, `createdAt`, `lastUsedAt`, `expiresAt`, `revokedAt`) for a user. Never returns `tokenHash` or raw tokens.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Widget token metadata list", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "tokens" ], "properties": { "tokens": { "type": "array", "items": { "type": "object", "required": [ "id", "deviceId", "platform", "scopes", "createdAt", "lastUsedAt", "expiresAt", "revokedAt" ], "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "platform": { "type": "string", "enum": [ "android", "ios" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } } } }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" } } }, "delete": { "tags": [ "Admin" ], "summary": "Revoke one or all widget tokens for a user (admin)", "description": "Requires a Clerk session with a platform admin role. Revokes a specific `tokenId` (query or JSON body) or all active widget tokens for `userId` and records an admin audit entry.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tokenId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Widget token(s) revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetTokenRevokeSuccess" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } } }, "400": { "description": "VALIDATION_ERROR" }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenId": { "type": "string" } } } } } } } }, "/api/v1/widgets/snapshot": { "get": { "tags": [ "Engage" ], "summary": "Get the signed-in fan’s widget snapshot", "description": "Returns personalized Rank / Fan Rep and HQ Live data. Provide a Clerk session (bearer or cookie) or a widget bearer scoped to `widgets:snapshot:read`. Request `?include=clubs` for up to six favorite or followed clubs. If a game in the returned snapshot is live, the private cache max age is 60 seconds; otherwise it is 3600. A weak ETag ignores `updatedAt`; a matching `If-None-Match` returns 304 without a body.", "security": [ { "bearerAuth": [] }, { "widgetBearerAuth": [] } ], "parameters": [ { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated optional slices. Pass `clubs` to add up to six favorite or followed clubs. Without it, the clubs field is omitted." }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Previously returned weak ETag for conditional revalidation." } ], "responses": { "200": { "description": "Personalized widget snapshot", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "private, max-age=60", "private, max-age=3600" ] } }, "ETag": { "schema": { "type": "string", "description": "Weak ETag (`W/\"\"`) computed over the snapshot state." } }, "Vary": { "schema": { "type": "string", "const": "Authorization, Cookie" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSnapshotSuccess" } } } }, "304": { "description": "Not Modified (snapshot state unchanged for the supplied `If-None-Match` ETag)", "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "private, max-age=60", "private, max-age=3600" ] } }, "ETag": { "schema": { "type": "string", "description": "Weak ETag (`W/\"\"`) computed over the snapshot state." } }, "Vary": { "schema": { "type": "string", "const": "Authorization, Cookie" } } } }, "401": { "description": "UNAUTHORIZED" }, "403": { "description": "FORBIDDEN (widget token lacks required scope)" }, "404": { "description": "USER_NOT_PROVISIONED" }, "429": { "description": "RATE_LIMITED (widget token exceeded 60 req/hr)" }, "500": { "description": "Unexpected error building the snapshot" }, "503": { "description": "RATE_LIMITER_UNAVAILABLE (widget-token verification)" } } } }, "/api/v1/app-clips/arena/{id}": { "get": { "tags": [ "App Clips", "Engage" ], "summary": "Public App Clip arena preview", "description": "Public, read-only preview for iOS App Clip invocations. id is a GameEvent.id, Team.id or Team.slug (1-128 of A-Z, a-z, 0-9, _ and -); a game is tried first. Returns { success, data: { kind: game_event | team, id, title, subtitle, venue, status, startTime, themeColor, logoUrl, homeTeam, awayTeam, team, checkInAvailable, fullAppUrl, checkInEndpoint } } with no personal data. checkInAvailable is true only for Engage partner clubs (and, for games, live or upcoming status); check-in itself stays on authenticated POST /api/v1/engage/quests/arena-check-in. Sends a weak ETag and returns 304 on a matching If-None-Match.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "description": "GameEvent.id, Team.id, or Team.slug" }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Public arena preview with a weak ETag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppClipArenaPreviewSuccess" } } }, "headers": { "ETag": { "description": "Weak ETag for the preview; send it back as If-None-Match", "schema": { "type": "string" } } } }, "304": { "description": "Not modified (If-None-Match matched)", "headers": { "ETag": { "description": "Weak ETag for the preview; send it back as If-None-Match", "schema": { "type": "string" } } } }, "400": { "description": "VALIDATION_ERROR (malformed id)" }, "404": { "description": "NOT_FOUND (no game or club matches id)" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Clerk session token. Use Authorization: Bearer ." }, "webhookSecret": { "type": "http", "scheme": "bearer", "description": "REVENUECAT_WEBHOOK_SECRET for /api/webhooks/revenuecat." }, "widgetBearerAuth": { "type": "http", "scheme": "bearer", "description": "Opaque wgt_ device credential. Accepted only for widget snapshot reads and revoking the presented widget token." } }, "schemas": { "ApprovedCopyLocaleContent": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "bullets" ], "properties": { "title": { "type": "string", "maxLength": 200, "minLength": 1 }, "body": { "type": "string", "maxLength": 8000 }, "bullets": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 500 } } } }, "ChangelogLocaleContent": { "type": "object", "additionalProperties": false, "required": [ "dateLabel", "title", "titlePlatform", "tags", "sections" ], "properties": { "dateLabel": { "type": "string", "maxLength": 80, "minLength": 1 }, "title": { "type": "string", "maxLength": 200, "minLength": 1 }, "titlePlatform": { "type": "string", "enum": [ "ios", "android", "all" ], "nullable": true }, "tags": { "type": "array", "maxItems": 40, "items": { "oneOf": [ { "type": "string", "maxLength": 80, "minLength": 1 }, { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "maxLength": 80, "minLength": 1 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] } } } ] } }, "sections": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "object", "properties": { "heading": { "type": "string", "maxLength": 160, "minLength": 1 }, "body": { "type": "string", "maxLength": 4000, "minLength": 1 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] }, "bullets": { "type": "array", "maxItems": 60, "items": { "oneOf": [ { "type": "string", "maxLength": 500 }, { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 500, "minLength": 1 }, "platform": { "type": "string", "enum": [ "ios", "android", "all" ] } } } ] } } } } } } }, "BinderLockedCard": { "type": "object", "description": "Binder shelf card. Other returned card fields are also present.", "properties": { "lockedBy": { "type": [ "string", "null" ], "description": "Lock token (`listing:` or `offer:`) of the owner's oldest locked holding of this collectible in the binder's wallet; null when no copy is reserved." }, "lockedQuantity": { "type": "integer", "minimum": 0, "description": "Copies reserved in this pocket: the wallet-wide reserved count for this collectible (a whole-row lock counts as the row quantity), capped at the card's quantity. 0 means no reserved copies; this is not the inventory reads' 0 = whole row encoding." }, "collectible": { "type": "object", "required": [ "finish", "cardTemplate" ], "properties": { "finish": { "type": [ "string", "null" ], "description": "Card finish id, or null when no finish is set." }, "cardTemplate": { "description": "Null when the card image has no verifiable published render.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CardTemplate" } ] } } } }, "required": [ "lockedBy", "lockedQuantity" ], "additionalProperties": true }, "InventoryLockedCollectible": { "type": "object", "description": "Collectible holding row. Other returned collectible fields are also present.", "properties": { "lockedBy": { "type": [ "string", "null" ], "description": "Lock token (`listing:` or `offer:`) while listed/offered; otherwise null." }, "lockedQuantity": { "type": "integer", "minimum": 0, "description": "Copies held by the lock; 0 with a token = whole row." }, "collectible": { "type": "object", "required": [ "finish", "cardTemplate" ], "properties": { "finish": { "type": [ "string", "null" ], "description": "Card finish id, or null when no finish is set." }, "cardTemplate": { "description": "Null when the card image has no verifiable published render.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CardTemplate" } ] } } } }, "additionalProperties": true }, "InventoryLockedPack": { "type": "object", "description": "Pack purchase row. Other returned pack fields are also present.", "properties": { "lockedBy": { "type": [ "string", "null" ], "description": "Lock token (`listing:` or `offer:`) while listed/offered; otherwise null." }, "collectibles": { "type": "array", "items": { "type": "object", "required": [ "finish", "cardTemplate" ], "properties": { "finish": { "type": [ "string", "null" ], "description": "Card finish id, or null when no finish is set." }, "cardTemplate": { "description": "Null when the card image has no verifiable published render.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CardTemplate" } ] } } } } }, "additionalProperties": true }, "WalletHoldings": { "type": "object", "required": [ "binderCount", "cardCount", "unopenedPackCount", "openedPackCount", "requiresAck" ], "properties": { "binderCount": { "type": "integer", "minimum": 0 }, "cardCount": { "type": "integer", "minimum": 0 }, "unopenedPackCount": { "type": "integer", "minimum": 0 }, "openedPackCount": { "type": "integer", "minimum": 0 }, "requiresAck": { "type": "boolean" } } }, "CardSerial": { "type": "object", "description": "Serial printed on an opened card. FINITE packs: number is the MintInstance serialNo and total the pack's mint count for that collectible. Unlimited packs: number comes from the per-collectible counter and total is null.", "required": [ "number", "total" ], "properties": { "number": { "type": "integer", "minimum": 1 }, "total": { "type": [ "integer", "null" ], "minimum": 1 } } }, "PackOpenBonusDto": { "type": "object", "description": "Idempotent pack-open rarity bonus. Null on the envelope when no rarity matched three. Replay returns the same payload with alreadyApplied true.", "required": [ "purchaseId", "rarity", "requested", "awarded", "alreadyApplied" ], "properties": { "purchaseId": { "type": "string" }, "rarity": { "type": "string" }, "requested": { "type": "integer" }, "awarded": { "type": "integer", "description": "Fan Rep actually credited. May be below requested when the Fan cap applies." }, "alreadyApplied": { "type": "boolean" } } }, "PrizeWheelSpinActionInput": { "type": "object", "description": "prize-wheel-spin action input. The client never chooses the segment.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "spin" ] } }, "additionalProperties": true }, "GuessThePlayerActionInput": { "type": "object", "description": "guess-the-player action input. The answer is server-held.", "required": [ "playerId" ], "properties": { "playerId": { "type": "string", "minLength": 1 } } }, "PrizeWheelSpinActionOutcome": { "type": "object", "required": [ "id", "label", "segmentId", "kind", "pointsAwarded", "collected", "weeklyBonusClaimed", "spinsUsed", "spinsRemaining", "presentOutcome" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "segmentId": { "type": "string" }, "kind": { "type": "string", "enum": [ "coin", "collect" ] }, "pointsAwarded": { "type": "integer" }, "collected": { "type": "object", "additionalProperties": { "type": "integer" } }, "weeklyBonusAwarded": { "type": "integer" }, "weeklyBonusClaimed": { "type": "boolean" }, "spinsUsed": { "type": "integer" }, "spinsRemaining": { "type": "integer" }, "presentOutcome": { "type": "object", "required": [ "angle", "segmentId" ], "properties": { "angle": { "type": "number" }, "segmentId": { "type": "string" } } } } }, "GuessThePlayerActionOutcome": { "type": "object", "required": [ "id", "label", "correct", "attemptsUsed", "clues", "status" ], "properties": { "id": { "type": "string" }, "label": { "type": "string", "enum": [ "correct", "incorrect" ] }, "correct": { "type": "boolean" }, "attemptsUsed": { "type": "integer" }, "clues": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value", "revealed" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "revealed": { "type": "boolean" } } } }, "status": { "type": "string", "enum": [ "ACTIVE", "WON", "LOST" ] }, "pointsAwarded": { "type": "integer" } } }, "UserSearchUser": { "type": "object", "description": "Public search row. Image URL is `profileUrl` (not `avatar`). There is no `level`. `handle` may be null on the default scope; `scope=mention` only returns non-empty handles. `location` is a profile field on every row — only the default scope also matches and ranks on it.", "required": [ "id", "name", "handle", "profileUrl", "profileUrlThumbhash", "bio", "location", "favoriteTeam", "stats" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "handle": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "profileUrlThumbhash": { "type": [ "string", "null" ] }, "bio": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "favoriteTeam": { "type": [ "string", "null" ] }, "stats": { "type": "object", "required": [ "followerCount", "followingCount", "totalPoints" ], "properties": { "followerCount": { "type": "integer" }, "followingCount": { "type": "integer" }, "totalPoints": { "type": "integer" } } } } }, "IdleLedgerGeneratorState": { "type": "object", "required": [ "generatorId", "owned" ], "properties": { "generatorId": { "type": "string", "enum": [ "rookie-card", "foam-finger-stand", "zamboni-fleet", "banner-press" ] }, "owned": { "type": "integer" } } }, "LedgerState": { "type": "object", "description": "locker-singularity idle ledger wire state. Buzz counters are BigInt serialized as decimal strings. Additive-only wire evolution (d-sports-api#682).", "required": [ "buzz", "lifetimeBuzz", "cumulativeBuzz", "playbooks", "generators", "milestonesClaimed", "upgrades", "rings", "totalRings", "prestigeCount", "multiplier", "prestigeUnlocked", "version", "lastSeenAt" ], "properties": { "buzz": { "type": "string", "description": "BigInt serialized as decimal string." }, "lifetimeBuzz": { "type": "string", "description": "BigInt serialized as decimal string." }, "cumulativeBuzz": { "type": "string", "description": "BigInt serialized as decimal string." }, "playbooks": { "type": "integer" }, "generators": { "type": "array", "items": { "$ref": "#/components/schemas/IdleLedgerGeneratorState" } }, "milestonesClaimed": { "type": "array", "items": { "type": "string" } }, "upgrades": { "type": "array", "items": { "type": "string" } }, "rings": { "type": "integer", "description": "Most recent prestige grant (informational); totalRings is the cumulative balance." }, "totalRings": { "type": "integer" }, "prestigeCount": { "type": "integer" }, "multiplier": { "type": "number" }, "prestigeUnlocked": { "type": "boolean" }, "version": { "type": "integer" }, "lastSeenAt": { "type": "string", "format": "date-time" } } }, "MobileVersionSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/MobileVersionData" } }, "required": [ "success", "data" ] }, "MobileVersionData": { "type": "object", "properties": { "latestVersion": { "type": "string" }, "iosStoreUrl": { "type": "string" }, "iosLatestVersion": { "type": [ "string", "null" ] }, "iosTestflightUrl": { "type": [ "string", "null" ] }, "iosAppleId": { "type": [ "string", "null" ] }, "iosStoreEnabled": { "type": "boolean" }, "androidStoreUrl": { "type": "string" }, "androidStoreEnabled": { "type": "boolean" }, "androidTestingUrl": { "type": [ "string", "null" ] }, "messageForce": { "type": [ "string", "null" ] }, "messageSoft": { "type": [ "string", "null" ] }, "androidApkUrl": { "type": [ "string", "null" ] }, "androidApkReleaseUrl": { "type": [ "string", "null" ] }, "androidApkVersion": { "type": [ "string", "null" ] }, "androidApkBuildId": { "type": [ "string", "null" ] }, "androidApkPublishedAt": { "type": [ "string", "null" ] }, "teamHqEnabled": { "type": "boolean" }, "packOpen": { "type": "object", "properties": { "engine": { "$ref": "#/components/schemas/PackOpenEngine" }, "reveal": { "$ref": "#/components/schemas/PackRevealConfig" }, "finish": { "$ref": "#/components/schemas/PackFinishConfig" }, "fixture": { "$ref": "#/components/schemas/PackFixtureConfig" } }, "required": [ "engine", "reveal", "finish", "fixture" ] }, "updatedAt": { "type": "string" }, "inviteRequiredFrom": { "type": [ "string", "null" ] }, "inviteRequiredUntil": { "type": [ "string", "null" ] }, "inviteRequired": { "type": "boolean" } }, "required": [ "latestVersion", "iosStoreUrl", "iosLatestVersion", "iosTestflightUrl", "iosAppleId", "iosStoreEnabled", "androidStoreUrl", "androidStoreEnabled", "androidTestingUrl", "messageForce", "messageSoft", "androidApkUrl", "androidApkReleaseUrl", "androidApkVersion", "androidApkBuildId", "androidApkPublishedAt", "teamHqEnabled", "packOpen", "updatedAt", "inviteRequiredFrom", "inviteRequiredUntil", "inviteRequired" ] }, "LaunchGateError": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error" ] }, "InviteMeSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/InviteMeView" } }, "required": [ "success", "data" ] }, "InviteMeView": { "type": "object", "properties": { "code": { "type": "string" }, "url": { "type": "string" }, "usedCount": { "type": "integer" }, "nextThreshold": { "type": [ "integer", "null" ] }, "grants": { "type": "array", "items": { "type": "integer" } } }, "required": [ "code", "url", "usedCount", "nextThreshold", "grants" ] }, "InvitePublicSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/InvitePublicView" } }, "required": [ "success", "data" ] }, "InvitePublicView": { "type": "object", "properties": { "valid": { "type": "boolean" }, "kind": { "$ref": "#/components/schemas/InviteKind" }, "label": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "valid", "kind", "label", "expiresAt" ] }, "InviteKind": { "type": "string", "enum": [ "CAMPAIGN", "VIP", "REFERRAL" ] }, "InviteRedeemSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/InviteRedeemView" } }, "required": [ "success", "data" ] }, "InviteRedeemView": { "type": "object", "properties": { "code": { "type": "string" }, "kind": { "$ref": "#/components/schemas/InviteKind" }, "alreadyRedeemed": { "type": "boolean" } }, "required": [ "code", "kind", "alreadyRedeemed" ] }, "RedeemInviteBody": { "type": "object", "properties": { "platform": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "PackGlbMedia": { "type": "object", "description": "Runtime texture-swap payload. One shared template GLB (modelUrl) plus pack art and team-default art, served separately. glbTemplateVersion is null when undeclared. 0 is pack materials FRONT and BACK with KHR_texture_transform, so pack art is contained in the UV window on a 1024x1536 canvas. 1 is the card case (TeamArt and CardBack). 2 is the combined pack opening (FRONT, BACK, TeamArt, CardBack) whose FRONT/BACK texture is a full-bleed 1104x1536 canvas with no texture transform. glbIdleClip is null when idle is off; CaseIdle is valid only for version 2. Texture names are not materials.", "required": [ "teamId", "modelUrl", "glbTemplateVersion", "glbIdleClip", "packArtFrontUrl", "packArtBackUrl", "cardCaseArtUrl", "cardBackArtUrl", "teamDefaultPackArtFrontUrl", "teamDefaultPackArtBackUrl", "teamDefaultCardCaseArtUrl", "teamDefaultCardBackArtUrl" ], "properties": { "teamId": { "type": [ "string", "null" ] }, "modelUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$", "description": "Served template URL: Pack.modelUrl, else animationId when modelUrl is null." }, "glbTemplateVersion": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Null means undeclared. 0 is FRONT/BACK with KHR_texture_transform (1024x1536 UV window). 1 is the card case. 2 is the combined opening (full-bleed 1104x1536 pack faces). Never defaulted." }, "glbIdleClip": { "type": [ "string", "null" ], "description": "Null means idle is off. The only non-null value is CaseIdle, and only when glbTemplateVersion is 2." }, "packArtFrontUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$" }, "packArtBackUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$" }, "cardCaseArtUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$" }, "cardBackArtUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$" }, "teamDefaultPackArtFrontUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$" }, "teamDefaultPackArtBackUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$" }, "teamDefaultCardCaseArtUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$" }, "teamDefaultCardBackArtUrl": { "type": [ "string", "null" ], "pattern": "^https://\\S+$" } } }, "PackOpenRepDto": { "type": "object", "description": "Fan Rep credited by this pack open (RepLedgerEntry earnKind packOpen). Separate from the rarity bonus (PackOpenBonusDto).", "required": [ "awarded", "total", "alreadyApplied" ], "properties": { "awarded": { "type": "integer", "minimum": 1, "description": "Fan Rep this open credited." }, "total": { "type": [ "integer", "null" ], "description": "Lifetime Fan Rep after the credit (same sum as the user profile fanRep). Null when that read failed." }, "alreadyApplied": { "type": "boolean", "description": "True on a replay of an already-opened purchase." } } }, "PlayerSeasonStatDerived": { "type": "object", "required": [ "gamesCounted", "goals", "assists", "points", "pim" ], "properties": { "gamesCounted": { "type": "integer", "minimum": 0, "description": "Team's final league games (team GP)." }, "goals": { "type": "integer", "minimum": 0 }, "assists": { "type": "integer", "minimum": 0 }, "points": { "type": "integer", "minimum": 0, "description": "goals + assists" }, "pim": { "type": "integer", "minimum": 0 } } }, "PlayerSeasonStatEffective": { "type": "object", "required": [ "gamesCounted", "gamesPlayed", "goals", "assists", "points", "pim", "goalieTier", "starTier" ], "properties": { "gamesCounted": { "type": "integer", "minimum": 0 }, "gamesPlayed": { "type": "integer", "minimum": 0, "description": "Override, else gamesCounted." }, "goals": { "type": "integer", "minimum": 0 }, "assists": { "type": "integer", "minimum": 0 }, "points": { "type": "integer", "minimum": 0, "description": "Effective goals + assists." }, "pim": { "type": "integer", "minimum": 0 }, "goalieTier": { "type": [ "string", "null" ], "enum": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC", null ] }, "starTier": { "type": [ "string", "null" ], "enum": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC", null ] } } }, "PlayerSeasonStatRow": { "type": "object", "required": [ "player", "season", "leagueVendorId", "source", "computedAt", "derived", "effective", "overridden" ], "properties": { "player": { "type": "object", "required": [ "id", "name", "position", "jerseyNumber" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "string" }, "jerseyNumber": { "type": [ "integer", "null" ] } } }, "season": { "type": "integer" }, "leagueVendorId": { "type": [ "integer", "null" ], "description": "API-Sports league counted (ICE Hockey League = 70)." }, "source": { "type": "string", "enum": [ "events" ] }, "computedAt": { "type": "string", "format": "date-time" }, "derived": { "$ref": "#/components/schemas/PlayerSeasonStatDerived" }, "effective": { "$ref": "#/components/schemas/PlayerSeasonStatEffective" }, "overridden": { "type": "array", "items": { "type": "string", "enum": [ "gamesPlayed", "goals", "assists", "pim", "goalieTier", "starTier" ] } } } }, "PlayerSeasonStatOverride": { "type": "object", "additionalProperties": false, "properties": { "gamesPlayed": { "type": "integer", "minimum": 0, "maximum": 200 }, "goals": { "type": "integer", "minimum": 0, "maximum": 1000 }, "assists": { "type": "integer", "minimum": 0, "maximum": 1000 }, "pim": { "type": "integer", "minimum": 0, "maximum": 1000 }, "goalieTier": { "type": "string", "enum": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC" ] }, "starTier": { "type": "string", "enum": [ "COMMON", "RARE", "EPIC", "LEGENDARY", "MYTHIC" ] } } }, "CardValueBreakdown": { "type": "object", "description": "How value was computed: value = round(rarityBase × subjectFactor × momentFactor). Display only; credits nothing. A future market multiplier (marketFactor) is reserved and never sent in v1.", "required": [ "rarityBase", "subjectFactor", "momentFactor", "momentType" ], "properties": { "rarityBase": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Points for the card's rarity: team override, else platform default." }, "subjectFactor": { "type": "number", "minimum": 0.1, "maximum": 10, "description": "Who is on the card (franchise 2.0, depth 1.0)." }, "momentFactor": { "type": "number", "minimum": 0.1, "maximum": 10, "description": "Multiplier for momentType." }, "momentType": { "type": "string", "enum": [ "PORTRAIT", "ACTION", "MILESTONE", "GAME_WINNER" ] } } }, "CardValueSettings": { "type": "object", "description": "Card value tables. effectiveRarityBases = the team's override where set, else the platform default.", "required": [ "platformRarityBases", "teamId", "teamRarityBases", "effectiveRarityBases", "momentFactors" ], "properties": { "platformRarityBases": { "type": "object", "additionalProperties": false, "properties": { "COMMON": { "type": "integer" }, "RARE": { "type": "integer" }, "EPIC": { "type": "integer" }, "LEGENDARY": { "type": "integer" }, "MYTHIC": { "type": "integer" } } }, "teamId": { "type": [ "string", "null" ] }, "teamRarityBases": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "COMMON": { "type": "integer" }, "RARE": { "type": "integer" }, "EPIC": { "type": "integer" }, "LEGENDARY": { "type": "integer" }, "MYTHIC": { "type": "integer" } } } ], "description": "Only the team's overrides; null without teamId." }, "effectiveRarityBases": { "type": "object", "additionalProperties": false, "properties": { "COMMON": { "type": "integer" }, "RARE": { "type": "integer" }, "EPIC": { "type": "integer" }, "LEGENDARY": { "type": "integer" }, "MYTHIC": { "type": "integer" } } }, "momentFactors": { "type": "object", "additionalProperties": false, "properties": { "PORTRAIT": { "type": "number" }, "ACTION": { "type": "number" }, "MILESTONE": { "type": "number" }, "GAME_WINNER": { "type": "number" } } } } }, "CardPlayer": { "type": "object", "description": "Roster player linked to a collectible (Collectible.playerId, mint-locked like rarity). name, position and jerseyNumber are read live from the Player row on every read, replays included; teamName is the collectible's team (the card's club).", "required": [ "id", "name", "position", "jerseyNumber", "teamName" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Roster name. The card title stays the collectible name." }, "position": { "type": [ "string", "null" ], "description": "Roster position code as stored (F, C, LW, RW, D, G, ...); null when blank." }, "jerseyNumber": { "type": [ "integer", "null" ] }, "teamName": { "type": [ "string", "null" ], "description": "Name of the collectible's team (the card's club), not the player's current team. Null only when the card has no team row." } } }, "SocialAccount": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "platform": { "type": "string", "enum": [ "x" ] }, "handle": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "connected", "disconnected", "expired" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "SocialScheduledPost": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "platform": { "type": "string", "enum": [ "x" ] }, "content": { "type": "string" }, "mediaUrls": { "type": "array", "items": { "type": "string" } }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "scheduled", "sending", "published", "failed", "cancelled" ] }, "externalId": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "result": { "type": [ "object", "null" ] }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "PickemOption": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,32}$" }, "label": { "type": "string" }, "teamId": { "type": "string" }, "playerId": { "type": "string" } }, "additionalProperties": false }, "PickemTeam": { "type": "object", "required": [ "name", "abbr" ], "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "abbr": { "type": "string" }, "logoUrl": { "type": "string" } }, "additionalProperties": false }, "PickemScenario": { "type": "object", "required": [ "promptId", "prompt", "options" ], "properties": { "promptId": { "type": "string" }, "prompt": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PickemOption" }, "minItems": 2, "maxItems": 6 }, "gameId": { "type": "string" }, "leagueId": { "type": "string" }, "locksAt": { "type": "string", "format": "date-time" }, "home": { "$ref": "#/components/schemas/PickemTeam" }, "away": { "$ref": "#/components/schemas/PickemTeam" }, "resolved": { "type": "boolean" }, "revealedWinningKey": { "type": "string" } }, "additionalProperties": false }, "PickemLeg": { "type": "object", "required": [ "legId", "prompt", "options", "gameId", "locksAt" ], "properties": { "legId": { "type": "string" }, "prompt": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PickemOption" } }, "gameId": { "type": "string" }, "leagueId": { "type": "string" }, "locksAt": { "type": "string", "format": "date-time" }, "home": { "$ref": "#/components/schemas/PickemTeam" }, "away": { "$ref": "#/components/schemas/PickemTeam" }, "winningKey": { "type": "string", "description": "Omitted until the fixture has an authoritative final result." }, "status": { "type": "string", "enum": [ "upcoming", "live", "final", "postponed", "delayed", "suspended", "cancelled" ] }, "locked": { "type": "boolean", "description": "True when authoritative status/start disallows a fresh selection." } }, "additionalProperties": false }, "PickemBoard": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "const": "global" } }, "additionalProperties": false }, { "type": "object", "required": [ "kind", "teamId" ], "properties": { "kind": { "type": "string", "const": "team" }, "teamId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } ] }, "PickemParlayInput": { "type": "object", "required": [ "idempotencyKey", "board", "picks" ], "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 }, "board": { "$ref": "#/components/schemas/PickemBoard" }, "picks": { "type": "array", "items": { "type": "object", "required": [ "legId", "optionKey" ], "properties": { "legId": { "type": "string", "minLength": 1, "maxLength": 300 }, "optionKey": { "type": "string", "enum": [ "home", "away", "tie" ] } }, "additionalProperties": false }, "minItems": 2 } }, "additionalProperties": false }, "PickemParlayPick": { "type": "object", "required": [ "legId", "optionKey" ], "properties": { "legId": { "type": "string" }, "optionKey": { "type": "string" }, "result": { "type": "string", "enum": [ "PENDING", "WON", "LOST", "VOID" ] } }, "additionalProperties": false }, "PickemParlayReceipt": { "type": "object", "required": [ "parlayId", "board", "picks", "status", "potentialBonus", "createdAt" ], "properties": { "parlayId": { "type": "string" }, "dayKey": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "board": { "$ref": "#/components/schemas/PickemBoard" }, "picks": { "type": "array", "items": { "$ref": "#/components/schemas/PickemParlayPick" } }, "status": { "type": "string", "enum": [ "OPEN", "WON", "LOST", "VOID" ] }, "potentialBonus": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Initial server-computed bonus; 2=10, 3=25, 4=50, 5+=100." }, "awardedBonus": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Actual credited bonus after void legs are removed; zero before credit." }, "createdAt": { "type": "string", "format": "date-time" }, "awardedRep": { "type": "integer", "minimum": 0, "description": "Total additional normal leg Rep credited; excludes the existing engine-session award and bonus." } }, "additionalProperties": false }, "TeamNameDisplayMode": { "type": "string", "description": "How club names are shown on web and engage-native. full is city plus name (Montreal Canadiens). name_only is the club name (Canadiens). Stored on UserSettings.teamNameDisplayMode. Default full.", "enum": [ "full", "name_only" ], "default": "full" }, "PackOpenEngine": { "type": "string", "enum": [ "webview", "video", "2d" ] }, "PackRevealConfig": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,31}$" }, "maxItems": 16 }, "PackFinishConfig": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,31}$" }, "maxItems": 16 }, "CustomizerPreviewMode": { "type": "string", "description": "Pinned customizer preview size for the fan (#931). full is the default size. compact shrinks the preview on scroll. Stored on UserSettings.customizerPreviewMode. Default full.", "enum": [ "full", "compact" ], "default": "full" }, "PackAntialias": { "type": "string", "description": "Pack-opening antialiasing mode for the fan (#923). auto lets the device pick a tier. The server stores the choice and does not know device tiers. Stored on UserSettings.packAntialias. Default auto.", "enum": [ "auto", "off", "fxaa", "smaa", "msaa" ], "default": "auto" }, "PackQuality": { "type": "string", "description": "Pack-opening quality mode (#854, native W8). The server stores the choice; the device resolves auto. Stored on UserSettings.packQuality. New rows default to auto.", "enum": [ "auto", "low", "mid", "high" ] }, "PackSummaryLayout": { "type": "string", "description": "Fan layout for the 3D pack-opening summary (#1155, native#1381). The server stores the choice; native renders it. auto is the device default (today grid). Stored on UserSettings.packSummaryLayout. New rows default to auto.", "enum": [ "auto", "grid", "compact", "carousel", "marquee" ] }, "PackOpenAction": { "type": "string", "description": "Wire value for the Open now / Open later default (#930). open_later is the inert default: the server never opens a pack from this preference. Stored as the PackOpenAction enum OPEN_NOW | OPEN_LATER. Default open_later.", "enum": [ "open_now", "open_later" ], "default": "open_later" }, "PackOpenChoice": { "type": "object", "description": "Post-checkout Open now / Open later sheet preference (#930), returned on GET and PATCH /api/user/settings. Per account. showSheet defaults true. defaultAction defaults open_later.", "additionalProperties": false, "required": [ "showSheet", "defaultAction" ], "properties": { "showSheet": { "type": "boolean", "default": true }, "defaultAction": { "$ref": "#/components/schemas/PackOpenAction" } } }, "CollectionSetDelta": { "type": "object", "required": [ "setId", "teamId", "title", "owned", "total", "missingCollectibleIds", "completed", "newlyCompleted", "reward" ], "properties": { "setId": { "type": "string" }, "teamId": { "type": "string" }, "title": { "type": "string" }, "owned": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "missingCollectibleIds": { "type": "array", "items": { "type": "string" } }, "completed": { "type": "boolean" }, "newlyCompleted": { "type": "boolean", "description": "True when this open is what finished the set." }, "reward": { "description": "Set when this call granted the cosmetic badge. Null otherwise.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "rewardId", "title" ], "properties": { "rewardId": { "type": "string" }, "title": { "type": "string" } } } ] } } }, "CollectibleSetProgressSet": { "type": "object", "required": [ "setId", "teamId", "title", "owned", "total", "missingCollectibleIds", "completed", "completedAt", "reward", "redeemable" ], "properties": { "setId": { "type": "string" }, "teamId": { "type": "string" }, "title": { "type": "string" }, "owned": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "missingCollectibleIds": { "type": "array", "items": { "type": "string" }, "description": "Sorted collectible ids the fan does not hold." }, "completed": { "type": "boolean" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the cosmetic badge was granted. Null until it is." }, "reward": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "rewardId", "title", "granted" ], "properties": { "rewardId": { "type": "string" }, "title": { "type": "string" }, "granted": { "type": "boolean" } } } ] }, "redeemable": { "type": "array", "description": "Missing common and rare members, with the point cost.", "items": { "type": "object", "required": [ "collectibleId", "rarity", "cost" ], "properties": { "collectibleId": { "type": "string" }, "rarity": { "type": "string", "enum": [ "COMMON", "RARE" ] }, "cost": { "type": "integer", "minimum": 1 } } } } } }, "SetPointMutation": { "type": "object", "required": [ "alreadyRecorded", "pointsDelta", "pointsBalance", "setId", "collectibleId", "quantity", "ownedAfter", "set", "reward" ], "properties": { "alreadyRecorded": { "type": "boolean", "description": "True when this idempotency key replayed a stored receipt." }, "pointsDelta": { "type": "integer", "description": "Positive on trade-in, negative on redeem. Never zero." }, "pointsBalance": { "type": "integer", "minimum": 0 }, "setId": { "type": "string" }, "collectibleId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "ownedAfter": { "type": "integer", "minimum": 0, "description": "Copies of this card the fan holds after the mutation." }, "set": { "type": "object", "required": [ "setId", "owned", "total", "missingCollectibleIds", "completed", "newlyCompleted" ], "properties": { "setId": { "type": "string" }, "owned": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "missingCollectibleIds": { "type": "array", "items": { "type": "string" } }, "completed": { "type": "boolean" }, "newlyCompleted": { "type": "boolean" } } }, "reward": { "description": "Set when this call granted the cosmetic badge. Null otherwise.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "rewardId", "title" ], "properties": { "rewardId": { "type": "string" }, "title": { "type": "string" } } } ] } } }, "SeasonState": { "type": "object", "description": "Off-season hub gate (#999). `state` is derived from the league's persisted hockey calendar window (never the gamification points season); `hubEnabled` is the switch native reads instead of a client `SHOW_OFFSEASON_HUB` constant. A manual `stateOverride` or `hubEnabled` on the window wins over the date math.", "required": [ "state", "hubEnabled" ], "properties": { "state": { "type": "string", "enum": [ "in_season", "off_season", "preseason" ] }, "hubEnabled": { "type": "boolean", "description": "True when the client should surface the off-season hub. Defaults to `state === \"off_season\"` unless the window pins it." } } }, "PackFixtureConfig": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,31}$" }, "maxItems": 16 }, "AppOpenSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppOpenData" } }, "required": [ "success", "data" ] }, "AppOpenData": { "type": "object", "properties": { "user": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": {}, "description": "Same as GET /api/user data for the caller." } }, "required": [ "ok", "data" ] }, { "$ref": "#/components/schemas/AppOpenSectionError" } ] }, "wallets": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppOpenWallet" } } }, "required": [ "ok", "data" ] }, { "$ref": "#/components/schemas/AppOpenSectionError" } ] }, "activeWalletAddress": { "type": [ "string", "null" ], "description": "Wallet the pack sections are scoped to: ?walletAddress= when the caller owns it, else the first non-hidden wallet, else the first wallet. Null with no wallets or when wallets failed." }, "packs": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "packs": { "type": "array", "items": { "type": "object", "additionalProperties": {}, "description": "Same item shape as GET /api/user/packs." } } }, "required": [ "packs" ] } }, "required": [ "ok", "data" ] }, { "$ref": "#/components/schemas/AppOpenSectionError" } ] }, "openedPacks": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "packs": { "type": "array", "items": { "type": "object", "additionalProperties": {}, "description": "Same item shape as GET /api/user/packs/opened." } } }, "required": [ "packs" ] } }, "required": [ "ok", "data" ] }, { "$ref": "#/components/schemas/AppOpenSectionError" } ] }, "notifications": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "unreadCount": { "type": "integer" } }, "required": [ "unreadCount" ] } }, "required": [ "ok", "data" ] }, { "$ref": "#/components/schemas/AppOpenSectionError" } ] }, "dsportsCash": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "dsportsCash": { "type": "integer" } }, "required": [ "dsportsCash" ] } }, "required": [ "ok", "data" ] }, { "$ref": "#/components/schemas/AppOpenSectionError" } ] }, "dailyQuest": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": {}, "description": "Same as GET /api/v1/engage/quests/daily-summary data." } }, "required": [ "ok", "data" ] }, { "$ref": "#/components/schemas/AppOpenSectionError" } ] } }, "required": [ "user", "wallets", "activeWalletAddress", "packs", "openedPacks", "notifications", "dsportsCash", "dailyQuest" ] }, "AppOpenSectionError": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "ok", "error", "code" ] }, "AppOpenWallet": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "createdAt": { "type": "string" }, "pinMigrationRequired": { "type": "boolean" }, "connectionType": { "type": "string", "enum": [ "CUSTODIAL", "EXTERNAL" ] }, "connectionProvider": { "type": [ "string", "null" ] }, "attestationMethod": { "type": [ "string", "null" ] }, "attestedAt": { "type": [ "string", "null" ] }, "attestationKid": { "type": [ "string", "null" ] }, "legalTermsVersion": { "type": [ "string", "null" ] }, "verified": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "label": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "isHidden": { "type": "boolean" } }, "required": [ "id", "address", "createdAt", "pinMigrationRequired", "connectionType", "connectionProvider", "attestationMethod", "attestedAt", "attestationKid", "legalTermsVersion", "verified", "sortOrder", "label", "color", "icon", "isHidden" ] }, "AppOpenError": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "success", "error" ] }, "CardTemplate": { "type": "object", "description": "Render template that produced the card image currently being served.", "required": [ "key", "version" ], "properties": { "key": { "type": "string" }, "version": { "type": "integer", "minimum": 1 } } }, "RenderSubmissionPresentation": { "type": "object", "properties": { "allowedActions": { "type": "array", "items": { "$ref": "#/components/schemas/RenderSubmissionAction" } }, "policyAllowsSelfApproval": { "type": [ "boolean", "null" ] }, "policyReasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "allowedActions", "policyAllowsSelfApproval", "policyReasons" ] }, "RenderSubmissionAction": { "type": "string", "enum": [ "cancel", "approve", "reject", "publish", "unpublish", "retry", "rerender", "submit" ] }, "SubmissionsErrorEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "$ref": "#/components/schemas/SubmissionsErrorCode" } }, "required": [ "success", "error", "code" ] }, "SubmissionsErrorCode": { "type": "string", "enum": [ "VALIDATION_ERROR", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "RATE_LIMIT_EXCEEDED", "INTERNAL_ERROR", "UNAUTHORIZED" ] }, "SubmissionsSuccessEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "presentation": { "$ref": "#/components/schemas/RenderSubmissionPresentation" } }, "required": [ "presentation" ], "additionalProperties": {} }, "code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "pagination": { "type": [ "object", "null" ], "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "additionalProperties": {} } }, "required": [ "success", "data" ] }, "CreateSubmissionBody": { "type": "object", "properties": { "teamId": { "type": "string", "minLength": 1 }, "templateKey": { "type": "string", "minLength": 1, "description": "Required for explicit template selection. Omit when choosing a card front by collectible." }, "cardFrontCollectibleId": { "type": "string", "minLength": 1, "description": "Collectible id or team-scoped slug. Selects a v1 card-front template from the collectible's rarity.", "pattern": "\\S" }, "sourceHasTransparency": { "type": "boolean", "description": "Set for transparent player cut-outs to allow Mythic Rays." }, "expectedTemplateKey": { "type": "string", "minLength": 1, "description": "Recommended card-front key already shown in the creator." }, "expectedTemplateVersion": { "type": "integer", "exclusiveMinimum": 0, "description": "Recommended card-front version already shown in the creator." }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "templateVersion": { "type": "integer", "exclusiveMinimum": 0 }, "metadata": { "type": "object", "properties": { "targetPackId": { "type": "string", "minLength": 1 }, "target": { "type": "string", "enum": [ "team_default" ] } }, "additionalProperties": {} } }, "required": [ "teamId", "idempotencyKey", "title" ], "description": "Choose an explicit template key (version optional), or a collectible-bound automatic card front. Card-front expectations must be supplied together; they assert the recommendation rather than override it. Template/target compatibility is validated server-side.", "oneOf": [ { "example": { "teamId": "milano-hc", "title": "Pack front artwork", "idempotencyKey": "pack-front-draft-001", "templateKey": "pack-art-front", "templateVersion": 2, "metadata": { "target": "team_default" } }, "required": [ "templateKey" ], "not": { "anyOf": [ { "required": [ "cardFrontCollectibleId" ] }, { "required": [ "sourceHasTransparency" ] }, { "required": [ "expectedTemplateKey" ] }, { "required": [ "expectedTemplateVersion" ] } ] } }, { "example": { "teamId": "milano-hc", "title": "Common player card front", "idempotencyKey": "card-front-draft-001", "cardFrontCollectibleId": "player-card", "expectedTemplateKey": "card-front-common-contour", "expectedTemplateVersion": 1 }, "required": [ "cardFrontCollectibleId" ], "not": { "anyOf": [ { "required": [ "templateKey" ] }, { "required": [ "templateVersion" ] } ] }, "dependentRequired": { "expectedTemplateKey": [ "expectedTemplateVersion" ], "expectedTemplateVersion": [ "expectedTemplateKey" ] } } ] }, "UpdateSubmissionDraftSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "title": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "title", "updatedAt" ] } }, "required": [ "success", "data" ] }, "UpdateSubmissionDraftBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "title" ], "additionalProperties": false }, "SubmissionSummary": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "templateKey": { "type": "string" }, "templateId": { "type": "string" }, "createdByUserId": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "queued", "rendering", "preview_ready", "changes_requested", "pending_platform_review", "approved", "publishing", "published", "unpublished", "render_failed", "cancelled", "expired" ] }, "version": { "type": "integer" }, "templateVersion": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "teamId", "slug", "title", "templateKey", "templateId", "createdByUserId", "status", "version", "templateVersion", "createdAt", "updatedAt", "submittedAt" ] }, "SubmissionListSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/SubmissionSummary" } }, "page": { "type": "number" }, "pageSize": { "type": "number" }, "total": { "type": "integer" } }, "required": [ "requests", "page", "pageSize", "total" ] } }, "required": [ "success", "data" ] }, "SubmissionTemplate": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "contentType": { "type": "string" }, "displayName": { "type": "string" }, "version": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "slotSpec": { "description": "Template slot specification stored as JSON." }, "outputSpec": { "description": "Template output specification stored as JSON." }, "requiresPlatformApproval": { "type": "boolean" } }, "required": [ "id", "key", "kind", "contentType", "displayName", "version", "description", "slotSpec", "outputSpec", "requiresPlatformApproval" ] }, "SubmissionTemplateListSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/SubmissionTemplate" } }, "recommendedTemplateId": { "type": "string", "description": "Recommended v1 card-front template for the latest collectible selection, when available." }, "unavailableTemplateKeys": { "type": "array", "items": { "type": "string" }, "description": "Pack-face keys with no compatible eligible version, when present." } }, "required": [ "templates" ] } }, "required": [ "success", "data" ] }, "CreateSubmissionSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "requestId": { "type": "string" }, "slug": { "type": "string" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "queued", "rendering", "preview_ready", "changes_requested", "pending_platform_review", "approved", "publishing", "published", "unpublished", "render_failed", "cancelled", "expired" ] }, "requiredSlots": { "type": "array", "items": { "type": "string" } }, "existing": { "type": "boolean" } }, "required": [ "requestId", "slug", "version", "status", "requiredSlots", "existing" ] } }, "required": [ "success", "data" ] }, "AppClipArenaPreview": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "game_event", "team" ] }, "id": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "startTime": { "type": [ "string", "null" ], "format": "date-time" }, "themeColor": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "homeTeam": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "abbr": { "type": "string" }, "score": { "type": [ "integer", "null" ] } }, "required": [ "id", "name", "abbr", "score" ] }, "awayTeam": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "abbr": { "type": "string" }, "score": { "type": [ "integer", "null" ] } }, "required": [ "id", "name", "abbr", "score" ] }, "team": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "nickname": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "id", "slug", "name", "nickname", "location" ] }, "checkInAvailable": { "type": "boolean" }, "fullAppUrl": { "type": "string", "format": "uri" }, "checkInEndpoint": { "type": "string" } }, "required": [ "kind", "id", "title", "subtitle", "venue", "status", "startTime", "themeColor", "logoUrl", "homeTeam", "awayTeam", "team", "checkInAvailable", "fullAppUrl", "checkInEndpoint" ] }, "AppClipArenaPreviewSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppClipArenaPreview" } }, "required": [ "success", "data" ] }, "AppleWalletPassBase64": { "type": "object", "properties": { "passTypeIdentifier": { "type": "string" }, "serialNumber": { "type": "string" }, "passKind": { "type": "string", "enum": [ "fan_id", "club_membership", "arena_event" ] }, "contentType": { "type": "string", "enum": [ "application/vnd.apple.pkpass" ] }, "filename": { "type": "string" }, "pkpassBase64": { "type": "string", "contentEncoding": "base64" } }, "required": [ "passTypeIdentifier", "serialNumber", "passKind", "contentType", "filename", "pkpassBase64" ] }, "AppleWalletPassBase64Success": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppleWalletPassBase64" } }, "required": [ "success", "data" ] }, "GoogleWalletPassSuccess": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "saveUrl", "jwt", "passKind", "objectId", "classId" ], "properties": { "saveUrl": { "type": "string", "format": "uri", "description": "Google Wallet Save URL containing the signed JWT." }, "jwt": { "type": "string", "description": "Signed Google Wallet savetowallet JWT." }, "passKind": { "type": "string", "enum": [ "fan_id", "club_membership", "arena_event" ] }, "objectId": { "type": "string" }, "classId": { "type": "string" } } } } }, "WidgetTokenIssueSuccess": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "token", "expiresAt" ], "properties": { "token": { "type": "string", "description": "Opaque `wgt_` bearer token returned once at issuance." }, "expiresAt": { "type": "string", "format": "date-time" } } } } }, "WidgetTokenRevokeSuccess": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "revoked", "revokedCount" ], "properties": { "revoked": { "type": "boolean", "const": true }, "revokedCount": { "type": "integer" } } } } }, "WidgetTeamSide": { "type": "object", "required": [ "abbr", "name", "score", "logo", "color" ], "properties": { "abbr": { "type": "string" }, "name": { "type": "string" }, "score": { "type": [ "integer", "null" ] }, "logo": { "type": [ "string", "null" ], "description": "Raster logo URL (`Team.logoPng`, or non-SVG fallback), or null." }, "color": { "type": [ "string", "null" ], "description": "Team.themeColor, falling back to the first nonblank Team.gradientColors entry, or null." } } }, "WidgetClubSnapshot": { "type": "object", "required": [ "teamId", "slug", "name", "abbr", "color", "logo", "game" ], "properties": { "teamId": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "abbr": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "game": { "type": [ "object", "null" ], "required": [ "gameId", "status", "startTime", "home", "away", "period", "clock", "appDeepLink" ], "properties": { "gameId": { "type": "string" }, "status": { "type": "string" }, "startTime": { "type": [ "string", "null" ], "format": "date-time" }, "home": { "$ref": "#/components/schemas/WidgetTeamSide" }, "away": { "$ref": "#/components/schemas/WidgetTeamSide" }, "period": { "type": [ "string", "null" ] }, "clock": { "type": [ "string", "null" ] }, "appDeepLink": { "type": "string", "description": "Native app deep link (`engagenative://hq/match/?slug=`)." } }, "description": "Best eligible non-demo game: live, soonest upcoming, then latest final; null when none qualifies." } } }, "WidgetSnapshotSuccess": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "rankOrPoints", "hqLive" ], "properties": { "rankOrPoints": { "type": "object", "required": [ "fanRep", "rank", "updatedAt", "deepLink" ], "properties": { "fanRep": { "type": "integer", "description": "Earned points plus Fan Rep ledger amounts." }, "rank": { "type": [ "integer", "null" ], "description": "Global rank by earned points (not combined Fan Rep), or null when unavailable." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Snapshot creation time." }, "deepLink": { "type": "string", "const": "/leaderboard" } } }, "hqLive": { "type": [ "object", "null" ], "required": [ "gameId", "slug", "status", "home", "away", "period", "clock", "lastPlay", "squadLabel", "deepLink", "appDeepLink" ], "properties": { "gameId": { "type": "string" }, "slug": { "type": [ "string", "null" ], "description": "Followed club slug for native HQ deep links." }, "status": { "type": "string", "const": "live" }, "home": { "$ref": "#/components/schemas/WidgetTeamSide" }, "away": { "$ref": "#/components/schemas/WidgetTeamSide" }, "period": { "type": [ "string", "null" ] }, "clock": { "type": [ "string", "null" ] }, "lastPlay": { "type": [ "string", "null" ], "description": "Newest play-by-play summary line clamped for widget display." }, "squadLabel": { "type": [ "string", "null" ], "description": "Split-squad label when the club has concurrent squads playing." }, "deepLink": { "type": "string", "description": "Relative web path under /locker-room/game/ (retained for backward compatibility)." }, "appDeepLink": { "type": "string", "description": "Native app deep link (`engagenative://hq/match/`), with `?slug=` when a club slug is available." } }, "description": "A live match involving a favorite or followed club, or null if none qualifies." }, "clubs": { "type": "array", "maxItems": 6, "items": { "$ref": "#/components/schemas/WidgetClubSnapshot" }, "description": "Present only with `include=clubs`. Up to six favorite or followed clubs, ordered by live games, upcoming games, final games, then clubs without an eligible game." } } } } } } } }