{"openapi":"3.1.0","info":{"title":"bollyiq API","version":"1.0.0","description":"REST API behind bollyiq.com and the bollyiq apps. Errors use application/problem+json. Guests identify with `X-Guest-Id` (a UUID the client stores; one is minted and returned in the `x-guest-id` response header if omitted). Signed-in users send `Authorization: Bearer <session token>` obtained from the Better Auth endpoints under /api/auth (email OTP, magic link, Google). Third-party/AI clients use OAuth 2.1 with PKCE (see /.well-known/oauth-authorization-server/api/auth) and the MCP server at /mcp.","license":{"name":"Proprietary"},"contact":{"email":"support@bollyiq.com"}},"servers":[{"url":"https://bollyiq.com"}],"security":[],"tags":[{"name":"Daily"},{"name":"Play"},{"name":"Battles"},{"name":"Me"},{"name":"Catalogue"},{"name":"Clubs"},{"name":"i18n"}],"paths":{"/api/v1/daily":{"get":{"tags":["Daily"],"operationId":"listDaily","summary":"Today's games and whether each is published","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"games":{"type":"array","items":{"$ref":"#/components/schemas/DailyGame"}}}}}}}}}},"/api/v1/daily/{game}":{"get":{"tags":["Daily"],"operationId":"getDaily","summary":"Public payload for today's puzzle (never answers)","parameters":[{"name":"game","in":"path","required":true,"description":"movie_mystery | song_detective | cinema_connections","schema":{"type":"string"}},{"name":"industry","in":"query","schema":{"enum":["hi","te","ta","ml","kn","bn"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyChallenge"}}}},"404":{"description":"Unknown game","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/attempts":{"post":{"tags":["Play"],"operationId":"startAttempt","summary":"Start a Movie Mystery / Song Detective attempt","security":[{"guestId":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["challengeId"],"properties":{"challengeId":{"type":"string"}}}}}},"responses":{"201":{"description":"Created. New guests receive x-guest-id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttemptStarted"}}}},"404":{"description":"Unknown or unpublished challenge","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/attempts/{aid}/reveal":{"post":{"tags":["Play"],"operationId":"revealClue","summary":"Reveal the next clue (costs points)","security":[{"guestId":[]},{"cookieAuth":[]}],"parameters":[{"name":"aid","in":"path","required":true,"description":"Attempt id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"clues":{"type":"array","items":{"type":"string"}},"cluesRevealed":{"type":"integer"}}}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Attempt finished","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/attempts/{aid}/guess":{"post":{"tags":["Play"],"operationId":"submitGuess","summary":"Submit a guess; scoring is server-authoritative","security":[{"guestId":[]},{"cookieAuth":[]}],"parameters":[{"name":"aid","in":"path","required":true,"description":"Attempt id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["guess"],"properties":{"guess":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuessResult"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Attempt finished","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/attempts/{aid}/share":{"post":{"tags":["Play"],"operationId":"shareAttempt","summary":"Create a spoiler-free public result link (finished attempts only)","security":[{"guestId":[]},{"cookieAuth":[]}],"parameters":[{"name":"aid","in":"path","required":true,"description":"Attempt id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareLink"}}}},"409":{"description":"Attempt not finished","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/connections/attempts":{"post":{"tags":["Play"],"operationId":"startConnections","summary":"Start a Cinema Connections attempt","security":[{"guestId":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["puzzleId"],"properties":{"puzzleId":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"attemptId":{"type":"string"},"grid":{"type":"array","items":{"type":"string"}},"maxMistakes":{"type":"integer"}}}}}}}}},"/api/v1/connections/attempts/{aid}/submit":{"post":{"tags":["Play"],"operationId":"submitConnectionsGroup","summary":"Submit four items as a group","security":[{"guestId":[]},{"cookieAuth":[]}],"parameters":[{"name":"aid","in":"path","required":true,"description":"Attempt id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":4,"maxItems":4,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionsResult"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Attempt finished","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/battles/sessions":{"post":{"tags":["Battles"],"operationId":"startBattles","summary":"Start a Cinema Battles session","security":[{"guestId":[]},{"cookieAuth":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"pair":{"type":"array","items":{"$ref":"#/components/schemas/BattleItem"}}}}}}}}}},"/api/v1/battles/sessions/{sid}/choice":{"post":{"tags":["Battles"],"operationId":"submitBattleChoice","summary":"Record a pick (or skip with pick:null) and get the next pair","security":[{"guestId":[]},{"cookieAuth":[]}],"parameters":[{"name":"sid","in":"path","required":true,"description":"Session id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["left","right","pick"],"properties":{"left":{"type":"string"},"right":{"type":"string"},"pick":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"pair":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BattleItem"}}}}}}}}}},"/api/v1/battles/sessions/{sid}/ranking":{"get":{"tags":["Battles"],"operationId":"getBattleRanking","summary":"Personal ranking from your picks","security":[{"guestId":[]},{"cookieAuth":[]}],"parameters":[{"name":"sid","in":"path","required":true,"description":"Session id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"basedOn":{"type":"integer"},"list":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/v1/battles/sessions/{sid}/dna":{"get":{"tags":["Battles"],"operationId":"getCinemaDna","summary":"Private Cinema DNA preview","security":[{"guestId":[]},{"cookieAuth":[]}],"parameters":[{"name":"sid","in":"path","required":true,"description":"Session id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dna"}}}}}},"post":{"tags":["Battles"],"operationId":"shareCinemaDna","summary":"Publish an approved-fields-only DNA snapshot (min 8 picks)","security":[{"guestId":[]},{"cookieAuth":[]}],"parameters":[{"name":"sid","in":"path","required":true,"description":"Session id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareLink"}}}},"409":{"description":"Too few choices","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/me":{"get":{"tags":["Me"],"operationId":"getMe","summary":"Signed-in profile summary","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"cinemaIq":{"$ref":"#/components/schemas/CinemaIq"}}}}}},"401":{"description":"Sign in first","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/me/history":{"get":{"tags":["Me"],"operationId":"getMyHistory","summary":"Recent finished games","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Sign in first","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/me/streak":{"get":{"tags":["Me"],"operationId":"getMyStreak","summary":"Daily streak (guest or account)","security":[{"guestId":[]},{"cookieAuth":[]},{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"tz","in":"query","description":"IANA time zone for the day boundary","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"streak":{"type":"integer"},"playedToday":{"type":"boolean"},"totalDays":{"type":"integer"},"timeZone":{"type":"string"}}}}}}}}},"/api/v1/me/claim":{"post":{"tags":["Me"],"operationId":"claimGuestHistory","summary":"Attach this device's guest history to the signed-in account","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"attempts":{"type":"integer"},"battleSessions":{"type":"integer"}}}}}},"401":{"description":"Sign in first","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/search":{"get":{"tags":["Catalogue"],"operationId":"search","summary":"Search films and stars in any script","parameters":[{"name":"lang","in":"query","description":"Locale for names (hi, te, ta, ...); overrides Accept-Language. Names render in that script when available, else English.","schema":{"type":"string"}},{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchHit"}}}}}}}}}},"/api/v1/movies/{slug}":{"get":{"tags":["Catalogue"],"operationId":"getMovie","summary":"Film with titles and credits","parameters":[{"name":"lang","in":"query","description":"Locale for names (hi, te, ta, ...); overrides Accept-Language. Names render in that script when available, else English.","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"description":"Film slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/people/{slug}":{"get":{"tags":["Catalogue"],"operationId":"getPerson","summary":"Person with filmography","parameters":[{"name":"lang","in":"query","description":"Locale for names (hi, te, ta, ...); overrides Accept-Language. Names render in that script when available, else English.","schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"description":"Person slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/industries/{code}/films":{"get":{"tags":["Catalogue"],"operationId":"listIndustryFilms","summary":"Popular films for an industry","parameters":[{"name":"lang","in":"query","description":"Locale for names (hi, te, ta, ...); overrides Accept-Language. Names render in that script when available, else English.","schema":{"type":"string"}},{"name":"code","in":"path","required":true,"description":"hi | te | ta | ml | kn | bn","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown industry","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/clubs/{slug}":{"get":{"tags":["Clubs"],"operationId":"getClub","summary":"Club summary: followers and whether you follow","security":[{},{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"Person slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/clubs/{slug}/follow":{"post":{"tags":["Clubs"],"operationId":"followClub","summary":"Follow (idempotent)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"Person slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Sign in","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["Clubs"],"operationId":"unfollowClub","summary":"Unfollow (idempotent)","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"Person slug","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/clubs/{slug}/posts":{"get":{"tags":["Clubs"],"operationId":"listClubPosts","summary":"Club feed (newest first, cursor via ?before=)","parameters":[{"name":"slug","in":"path","required":true,"description":"Person slug","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["Clubs"],"operationId":"createClubPost","summary":"Post to a club. kind labels the claim: opinion | rumor | sourced","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"Person slug","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":1000},"kind":{"enum":["opinion","rumor","sourced"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/posts/{id}":{"delete":{"tags":["Clubs"],"operationId":"removePost","summary":"Author or moderator removes a post","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Post id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/posts/{id}/comments":{"get":{"tags":["Clubs"],"operationId":"listComments","summary":"Comments on a post","parameters":[{"name":"id","in":"path","required":true,"description":"Post id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["Clubs"],"operationId":"createComment","summary":"Comment on a post","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Post id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/reports":{"post":{"tags":["Clubs"],"operationId":"report","summary":"Report a post or comment","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetType","targetId","reason"],"properties":{"targetType":{"enum":["post","comment"]},"targetId":{"type":"string"},"reason":{"enum":["harassment","hate","spam","impersonation","private_info","copyright","other"]}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/i18n/{locale}":{"get":{"tags":["i18n"],"operationId":"getMessages","summary":"UI string catalogue for a locale (shared by web and mobile)","parameters":[{"name":"locale","in":"path","required":true,"description":"en, hi, te, ta, ml, kn, bn, mr, gu, pa, or, as, ur","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"404":{"description":"Unknown locale","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Better Auth session token (header `set-auth-token` after sign-in) for first-party apps."},"cookieAuth":{"type":"apiKey","in":"cookie","name":"better-auth.session_token"},"guestId":{"type":"apiKey","in":"header","name":"X-Guest-Id","description":"Client-stored UUID identifying a guest. Omit to have one minted (returned in the x-guest-id header)."}},"schemas":{"Problem":{"type":"object","properties":{"title":{"type":"string"},"status":{"type":"integer"}},"required":["title","status"]},"DailyGame":{"type":"object","properties":{"game":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"webPath":{"type":"string"},"available":{"type":"boolean"}}},"DailyChallenge":{"type":"object","properties":{"game":{"type":"string"},"available":{"type":"boolean"},"id":{"type":"string"},"firstClue":{"type":"string"},"grid":{"type":"array","items":{"type":"string"}},"start":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"body":{"type":"object"}}}}},"AttemptStarted":{"type":"object","properties":{"attemptId":{"type":"string"},"clues":{"type":"array","items":{"type":"string"}},"cluesRevealed":{"type":"integer"},"maxClues":{"type":"integer"}}},"GuessResult":{"type":"object","properties":{"correct":{"type":"boolean"},"score":{"type":"integer"},"wrongLeft":{"type":"integer"},"answer":{"type":"string","description":"Only present once the attempt is finished."}}},"ConnectionsResult":{"type":"object","properties":{"result":{"enum":["correct","one_away","wrong"]},"mistakesLeft":{"type":"integer"},"finished":{"type":"boolean"},"group":{"type":"object"},"groups":{"type":"array","items":{"type":"object"}},"score":{"type":"integer"}}},"ShareLink":{"type":"object","properties":{"token":{"type":"string"},"url":{"type":"string","format":"uri"}}},"BattleItem":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"year":{"type":"integer"},"industry":{"type":"string"}}},"Dna":{"type":"object","properties":{"basedOn":{"type":"integer"},"industries":{"type":"object","additionalProperties":{"type":"number"}},"decade":{"type":["integer","null"]},"lean":{"type":"string"}}},"CinemaIq":{"type":"object","properties":{"games":{"type":"integer"},"calibrating":{"type":"boolean"},"rating":{"type":["integer","null"]},"gamesToGo":{"type":"integer"}}},"SearchHit":{"type":"object","properties":{"type":{"enum":["work","person"]},"name":{"type":"string"},"slug":{"type":"string"},"year":{"type":["integer","null"]}}}}}}