{"schemes":["http"],"swagger":"2.0","info":{"description":"Backend for the Astir family streaming platform: auth, parent/child profiles with permissions, content catalog, subscriptions & payments (Click), and signed streaming URLs.\n\n**Localization:** pass `?lang=uz|ru|en` (or `Accept-Language`) on any catalog/billing endpoint to receive resolved strings instead of the raw i18n map. Tag names, titles, and descriptions are all resolved. See `docs/i18n-localization.md` for the full spec.\n\n**Streaming grants:** `GET /stream/{id}/grant` returns `duration_sec` (full video length), `preview_only`, and `preview_until_sec` (15 s for non-subscribers). Display `duration_sec` in the player timeline; enforce `preview_until_sec` client-side — the server hard-blocks segments beyond that point regardless.","title":"Astir Streaming API","termsOfService":"https://astir-animation.uz/terms","contact":{"name":"Astir Team","email":"support@astir-animation.uz"},"license":{"name":"Proprietary"},"version":"0.1.0"},"host":"test-api.astir-animation.uz","basePath":"/api/v1","paths":{"/admin/cards":{"get":{"security":[{"BearerAuth":[]}],"description":"Returns all saved cards platform-wide. Optionally filter by user_id. Token hash is included for fingerprinting; the raw token is never exposed.","produces":["application/json"],"tags":["cards"],"summary":"List all cards (admin)","parameters":[{"type":"string","description":"Filter by user UUID","name":"user_id","in":"query"},{"type":"integer","description":"Page size","name":"limit","in":"query"},{"type":"integer","description":"Offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.AdminCardListResponse"}}}}},"/admin/faqs":{"get":{"security":[{"BearerAuth":[]}],"description":"Returns all FAQs including inactive ones, with full I18n maps for editing.","produces":["application/json"],"tags":["faq"],"summary":"List all FAQs (admin)","responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.FAQ"}}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["faq"],"summary":"Create a FAQ entry","parameters":[{"description":"FAQ payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.FAQRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.FAQ"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/admin/faqs/{id}":{"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["faq"],"summary":"Update a FAQ entry","parameters":[{"type":"string","description":"FAQ ID","name":"id","in":"path","required":true},{"description":"FAQ payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.FAQRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.FAQ"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["faq"],"summary":"Delete a FAQ entry","parameters":[{"type":"string","description":"FAQ ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/admin/support/chats":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["support-admin"],"summary":"[Admin] List support chats, most-recent activity first","parameters":[{"type":"integer","description":"Pagination limit (default 20)","name":"limit","in":"query"},{"type":"integer","description":"Pagination offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","schema":{"type":"object","additionalProperties":true}}}}},"/admin/support/chats/{id}":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["support-admin"],"summary":"[Admin] Get a support chat","parameters":[{"type":"string","description":"Chat ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.SupportChat"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/admin/support/chats/{id}/messages":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["support-admin"],"summary":"[Admin] List messages in a support chat","parameters":[{"type":"string","description":"Chat ID","name":"id","in":"path","required":true},{"type":"integer","description":"Page size (default 50, max 200)","name":"limit","in":"query"},{"type":"string","description":"Return messages older than this message ID","name":"before","in":"query"},{"type":"string","description":"Return messages newer than this message ID","name":"after","in":"query"}],"responses":{"200":{"description":"OK","schema":{"type":"object","additionalProperties":true}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["multipart/form-data"],"produces":["application/json"],"tags":["support-admin"],"summary":"[Admin] Reply in a support chat (with optional attachment up to 50 MB)","parameters":[{"type":"string","description":"Chat ID","name":"id","in":"path","required":true},{"type":"string","description":"Message text","name":"body","in":"formData"},{"type":"file","description":"Attachment (max 50 MB)","name":"file","in":"formData"}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.SupportMessage"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/admin/support/chats/{id}/read":{"post":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["support-admin"],"summary":"[Admin] Mark a support chat as read on the admin side","parameters":[{"type":"string","description":"Chat ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/admin/transactions":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["billing"],"summary":"All transactions (admin)","parameters":[{"enum":["pending","succeeded","failed","refunded","canceled"],"type":"string","description":"Filter by status","name":"status","in":"query"},{"type":"integer","description":"Page size","name":"limit","in":"query"},{"type":"integer","description":"Offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.TxListResponse"}}}}},"/auth/apple":{"post":{"description":"Accepts an Apple identity token from ASAuthorizationAppleIDCredential. Verifies the token with Apple's public keys, then finds or creates a parent account and returns a token pair. The user's name (given_name, family_name) is only provided by Apple on the very first sign-in — pass empty strings on subsequent calls.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Sign in with Apple (iOS)","parameters":[{"description":"Apple identity token + optional name","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.AppleAuthRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TokenPair"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/child/confirm":{"post":{"security":[{"BearerAuth":[]}],"description":"Single endpoint for the parent QR scanner. The backend detects the code type automatically.\\n- Pairing code (from /auth/child/init): child_id is required; links the device and optionally sets initial permissions.\\n- Extension code (from /children/{id}/extend/init): child_id is ignored; grants 2 more hours of watch time.\\nThe response field \"action\" tells the client which case was handled.","consumes":["application/json"],"produces":["application/json"],"tags":["children"],"summary":"Parent scans a child QR — handles both device pairing and session extension","parameters":[{"description":"Scanned code. child_id required only for pairing.","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ScanQRRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.ScanResult"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"410":{"description":"Gone","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/child/init":{"post":{"description":"The child's device calls this first. Display the returned QR on the child's screen. The parent scans it and calls POST /auth/child/confirm to select which child profile this device belongs to. Poll GET /auth/child/{device_id}/status until status=confirmed.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Child device initiates pairing — returns a QR the parent scans","parameters":[{"description":"device_name and device_fingerprint","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.PairRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.PairingTicket"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/child/{device_id}/status":{"get":{"description":"Returns status=pending until the parent confirms. Once confirmed, includes access_token and child profile so the device can start streaming.","produces":["application/json"],"tags":["auth"],"summary":"Child device polls for pairing confirmation","parameters":[{"type":"string","description":"Device ID returned by /auth/child/init","name":"device_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.ChildPairingStatus"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/forgot-password":{"post":{"description":"Same as /auth/otp/request but semantically for password reset. Follow up with /auth/otp/verify then /auth/reset-password.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Start password-reset flow (sends OTP to email)","parameters":[{"description":"Email","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ForgotPasswordRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.OTPRequestResult"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/google":{"post":{"description":"Accepts a Google ID token obtained from the Google Sign-In SDK on Android or iOS. Verifies the token with Google, then finds or creates a parent account and returns a token pair. On first sign-in the account is created automatically — no separate registration step needed.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Sign in with Google (Android / iOS)","parameters":[{"description":"Google ID token","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.GoogleAuthRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TokenPair"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/login":{"post":{"description":"Exchange email+password for an access/refresh token pair. Parents use the OTP flow.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Log in (staff only — super_admin, admin)","parameters":[{"description":"Staff credentials","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.LoginRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TokenPair"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/logout":{"post":{"consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Log out (revoke refresh token)","parameters":[{"description":"Refresh token to revoke","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.RefreshRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/auth/me":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["auth"],"summary":"Return the current user","responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.User"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}},"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Update current user's profile","parameters":[{"description":"Fields to update","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.UpdateProfileRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.User"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/me/avatar":{"post":{"security":[{"BearerAuth":[]}],"consumes":["multipart/form-data"],"produces":["application/json"],"tags":["auth"],"summary":"Upload a profile avatar image","parameters":[{"type":"file","description":"Avatar image (jpg/png/webp)","name":"file","in":"formData","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.User"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/otp/login":{"post":{"description":"Called when VerifyOTP returned user_exists=true. Validates the password and returns tokens.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Complete login after OTP verify (existing users)","parameters":[{"description":"Email + password","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.OTPLoginRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TokenPair"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/otp/request":{"post":{"description":"Starts the parent auth flow. In dev (OTP_DEFAULT_CODE set), the code is echoed back in debug_code and no email is sent.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Request an OTP code sent to an email address","parameters":[{"description":"Email to OTP","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.OTPRequestRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.OTPRequestResult"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/otp/verify":{"post":{"description":"Verifies the OTP. If user_exists=true the response already contains access_token + refresh_token — the user is logged in. If user_exists=false proceed to POST /auth/register with last_name, name and password.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Verify OTP code","parameters":[{"description":"Email + OTP code","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.OTPVerifyRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.OTPVerifyResult"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/refresh":{"post":{"consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Refresh an access token","parameters":[{"description":"Refresh token","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.RefreshRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TokenPair"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/register":{"post":{"description":"Called when VerifyOTP returned user_exists=false. Creates the account with name (required), last_name (optional), and password, then returns tokens.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Register a new parent account after OTP verify","parameters":[{"description":"Registration data","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.RegisterRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/service.TokenPair"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"409":{"description":"Conflict","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/reset-password":{"post":{"description":"Call after /auth/forgot-password → /auth/otp/verify. Uses the verified OTP session stored in Redis.","consumes":["application/json"],"produces":["application/json"],"tags":["auth"],"summary":"Set a new password after OTP verify","parameters":[{"description":"Email + new password","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ResetPasswordRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/auth/tv/confirm":{"post":{"security":[{"BearerAuth":[]}],"description":"Authenticated parent calls this after scanning the TV's QR code. Links the TV to the parent's account. Returns the profile list (\"who's watching?\").","consumes":["application/json"],"produces":["application/json"],"tags":["tv"],"summary":"TV: parent confirms pairing by scanning QR","parameters":[{"description":"Pairing code from QR","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.TVConfirmRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TVStatusResult"}}}}},"/auth/tv/init":{"post":{"description":"TV calls this on first launch. Displays the returned QR on screen. Parent scans it with their authenticated app (/auth/tv/confirm). TV then polls /auth/tv/:device_id/status until confirmed.","consumes":["application/json"],"produces":["application/json"],"tags":["tv"],"summary":"TV: generate pairing QR","parameters":[{"description":"TV device info","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.TVInitRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TVInitTicket"}}}}},"/auth/tv/profile":{"post":{"security":[{"BearerAuth":[]}],"description":"TV calls this with its device_token (tv audience). Pass child_id to stream as a child; omit (or null) to stream as the parent. Returns a short-lived streaming access_token.","consumes":["application/json"],"produces":["application/json"],"tags":["tv"],"summary":"TV: select who is watching","parameters":[{"description":"Profile to activate","name":"body","in":"body","schema":{"$ref":"#/definitions/handler.TVSelectProfileRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TVStreamSession"}}}}},"/auth/tv/profiles":{"get":{"security":[{"BearerAuth":[]}],"description":"TV calls this with its device_token to refresh the list of available profiles without re-selecting.","produces":["application/json"],"tags":["tv"],"summary":"TV: get current profile list","responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TVProfileList"}}}}},"/auth/tv/{device_id}/status":{"get":{"description":"TV polls this after displaying the QR. Returns status \"pending\" until parent confirms. Once confirmed, returns a device_token and profile list.","produces":["application/json"],"tags":["tv"],"summary":"TV: poll for pairing confirmation","parameters":[{"type":"string","description":"Device ID from /auth/tv/init","name":"device_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.TVStatusResult"}}}}},"/billing/charge/recurring":{"post":{"security":[{"BearerAuth":[]}],"description":"Calls Click's POST /card_token/payment. No user redirect needed — the charge is silent. The card must have been verified via POST /payments/click/card/verify first.","consumes":["application/json"],"produces":["application/json"],"tags":["billing"],"summary":"Charge a verified card token (recurring / subscription renewal)","parameters":[{"description":"Plan + card","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.RecurringChargeRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/service.CheckoutResult"}}}}},"/billing/checkout":{"post":{"security":[{"BearerAuth":[]}],"description":"Creates a pending subscription + transaction and returns the provider checkout URL. Redirect the user to `checkout_url`. In dev (no Click secrets), the URL points at the mock endpoint.","consumes":["application/json"],"produces":["application/json"],"tags":["billing"],"summary":"Start a subscription checkout","parameters":[{"description":"Checkout request","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.CheckoutRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/service.CheckoutResult"}}}}},"/billing/checkout/deeplink":{"post":{"security":[{"BearerAuth":[]}],"description":"Creates a pending subscription + transaction and returns a Click deeplink URL. Open the URL on the device — the Click app intercepts it, or the browser payment page opens as fallback.","consumes":["application/json"],"produces":["application/json"],"tags":["billing"],"summary":"Start a deeplink / hosted-page checkout","parameters":[{"description":"Plan to subscribe to","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.DeeplinkCheckoutRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/service.CheckoutResult"}}}}},"/billing/subscriptions":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["billing"],"summary":"My subscriptions","responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.Subscription"}}}}}},"/billing/transactions":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["billing"],"summary":"My transactions","parameters":[{"type":"integer","description":"Page size","name":"limit","in":"query"},{"type":"integer","description":"Offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.TxListResponse"}}}}},"/cards":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["cards"],"summary":"List my cards","responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.Card"}}}}},"post":{"security":[{"BearerAuth":[]}],"description":"Only brand + masked PAN + provider token are stored; raw PAN is never persisted. Works with the Click dev stub today — wire production to the provider's frontend tokenisation.","consumes":["application/json"],"produces":["application/json"],"tags":["cards"],"summary":"Tokenise and save a card","parameters":[{"description":"Card data","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.CardRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.Card"}}}}},"/cards/{id}":{"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["cards"],"summary":"Delete a card","parameters":[{"type":"string","description":"Card ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/cards/{id}/default":{"post":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["cards"],"summary":"Set a card as default","parameters":[{"type":"string","description":"Card ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/categories":{"get":{"produces":["application/json"],"tags":["categories"],"summary":"List categories","parameters":[{"enum":["film","series","cartoon","other"],"type":"string","description":"Filter by kind","name":"kind","in":"query"},{"enum":["uz","ru","en"],"type":"string","description":"Resolve i18n fields to this locale","name":"lang","in":"query"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.Category"}}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["categories"],"summary":"Create a category","parameters":[{"description":"Category payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.CategoryRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.Category"}}}}},"/categories/{id}":{"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["categories"],"summary":"Update a category","parameters":[{"type":"string","description":"Category ID","name":"id","in":"path","required":true},{"description":"Category payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.CategoryRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Category"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["categories"],"summary":"Delete a category","parameters":[{"type":"string","description":"Category ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/categories/{id}/poster":{"get":{"produces":["application/octet-stream"],"tags":["categories"],"summary":"Serve a category's poster image (public)","parameters":[{"type":"string","description":"Category ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK"},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["multipart/form-data"],"produces":["application/json"],"tags":["categories"],"summary":"Upload a poster image for a category","parameters":[{"type":"string","description":"Category ID","name":"id","in":"path","required":true},{"type":"file","description":"Image file (jpg/png/webp)","name":"file","in":"formData","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Category"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/children":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["children"],"summary":"List my children","responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.Child"}}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["children"],"summary":"Create a child profile","parameters":[{"description":"Child data","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ChildCreateRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.Child"}}}}},"/children/{id}":{"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["children"],"summary":"Update a child profile","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true},{"description":"Child data","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ChildUpdateRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Child"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["children"],"summary":"Delete a child profile","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/children/{id}/devices":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["children"],"summary":"List paired devices for a child","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.ChildDevice"}}}}}},"/children/{id}/devices/{device_id}":{"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["children"],"summary":"Revoke a paired child device","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true},{"type":"string","description":"Device ID","name":"device_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/children/{id}/extend/init":{"post":{"security":[{"BearerAuth":[]}],"description":"Alternative to PIN entry. The child's device shows this QR; the parent scans it and calls POST /auth/child/extend/confirm to grant 2 more hours.","produces":["application/json"],"tags":["children"],"summary":"Child initiates QR-based extension — returns a QR the parent scans","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.ExtensionTicket"}}}}},"/children/{id}/extend/pin":{"post":{"security":[{"BearerAuth":[]}],"description":"Called by the child's device when the watch window expires. Requires a PIN previously set by the parent.","consumes":["application/json"],"produces":["application/json"],"tags":["children"],"summary":"Child enters PIN to extend watch session by 2 hours","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true},{"description":"4-digit PIN","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ExtendByPINRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/children/{id}/extend/{ticket_id}/status":{"get":{"security":[{"BearerAuth":[]}],"description":"Returns \"pending\" until the parent scans the QR. Once confirmed, returns \"confirmed\" with extends_until.","produces":["application/json"],"tags":["children"],"summary":"Child polls extension ticket status","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true},{"type":"string","description":"Ticket ID from init response","name":"ticket_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.ExtensionTicketStatus"}}}}},"/children/{id}/permissions":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["children"],"summary":"List permissions applied to a child","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.ChildPermission"}}}}},"post":{"security":[{"BearerAuth":[]}],"description":"Rules target a category OR a specific content item. Time windows are minutes-of-day; WeekdayMask is a 7-bit field (Mon=bit0..Sun=bit6, 127=every day).","consumes":["application/json"],"produces":["application/json"],"tags":["children"],"summary":"Attach an allow/deny rule to a child","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true},{"description":"Rule","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.PermissionRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.ChildPermission"}}}}},"/children/{id}/permissions/{rule_id}":{"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["children"],"summary":"Update a child's permission rule in real time","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true},{"type":"string","description":"Permission ID","name":"rule_id","in":"path","required":true},{"description":"Rule","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.PermissionRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.ChildPermission"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["children"],"summary":"Remove a permission rule","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true},{"type":"string","description":"Permission ID","name":"rule_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/children/{id}/pin":{"put":{"security":[{"BearerAuth":[]}],"description":"The PIN lets the child self-extend their watch session by 2 hours without needing a parent scan.","consumes":["application/json"],"produces":["application/json"],"tags":["children"],"summary":"Set or replace the 4-digit PIN for a child (parent)","parameters":[{"type":"string","description":"Child ID","name":"id","in":"path","required":true},{"description":"4-digit PIN","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.SetPINRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/comments/{id}":{"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["comments"],"summary":"Edit your own comment","parameters":[{"type":"string","description":"Comment ID","name":"id","in":"path","required":true},{"description":"Comment body","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.CommentRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Comment"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["comments"],"summary":"Delete a comment (owner or admin)","parameters":[{"type":"string","description":"Comment ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/content":{"get":{"description":"Returns a unified list where each item has `item_type`: \"content\" (stream directly) or \"series\" (tap → GET /series/:id/episodes). Non-admin requests exclude individual episodes. Use `?kind=` to filter: \"film\" | \"cartoon\" | \"other\" returns only matching content; \"series\" returns only series cards. Omit `kind` to get everything. Pass `?lang=uz|ru|en` (or Accept-Language) for localized strings.","produces":["application/json"],"tags":["content"],"summary":"List content items (films, cartoons) + series cards","parameters":[{"enum":["film","cartoon","series","other"],"type":"string","description":"Filter by content type","name":"kind","in":"query"},{"type":"string","description":"Filter by specific category ID","name":"category_id","in":"query"},{"type":"string","description":"Title search","name":"q","in":"query"},{"type":"boolean","description":"Show all statuses and include individual episodes (admin only)","name":"admin","in":"query"},{"type":"integer","description":"Page size (default 20)","name":"limit","in":"query"},{"type":"integer","description":"Offset (default 0)","name":"offset","in":"query"},{"type":"string","description":"Comma-separated tag UUIDs (all must match)","name":"tag_ids","in":"query"},{"type":"integer","description":"Minimum age rating","name":"min_age","in":"query"},{"type":"integer","description":"Maximum age rating","name":"max_age","in":"query"},{"type":"boolean","description":"Only content liked by the authenticated user","name":"liked","in":"query"},{"enum":["uz","ru","en"],"type":"string","description":"Resolve i18n fields to this locale","name":"lang","in":"query"}],"responses":{"200":{"description":"Raw i18n map (admin, no lang param)","schema":{"$ref":"#/definitions/handler.ContentListResponse"}}}},"post":{"security":[{"BearerAuth":[]}],"description":"Use this to create a shell, then call `/content/{id}/upload` to attach the source file.","consumes":["application/json"],"produces":["application/json"],"tags":["content"],"summary":"Create content metadata (no file)","parameters":[{"description":"Content payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ContentRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.Content"}}}}},"/content/{id}":{"get":{"description":"Returns a localized response when `?lang=uz|ru|en` is provided or an `Accept-Language` header is sent. Omit both to receive the raw i18n map (admin use).","produces":["application/json"],"tags":["content"],"summary":"Get a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true},{"enum":["uz","ru","en"],"type":"string","description":"Resolve i18n fields to this locale","name":"lang","in":"query"}],"responses":{"200":{"description":"Localized response","schema":{"$ref":"#/definitions/handler.LocalizedContent"}}}},"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["content"],"summary":"Update content","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true},{"description":"Content payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ContentRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Content"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["content"],"summary":"Delete content","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/content/{id}/block":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["blocks"],"summary":"Check whether the current user has blocked a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.BlockStatusResponse"}}}},"post":{"security":[{"BearerAuth":[]}],"description":"Blocked content is hidden from all listings and cannot be streamed. Idempotent.","produces":["application/json"],"tags":["blocks"],"summary":"Block a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}},"delete":{"security":[{"BearerAuth":[]}],"description":"Removes the block — the content reappears in listings. Idempotent.","produces":["application/json"],"tags":["blocks"],"summary":"Unblock a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/content/{id}/comments":{"get":{"produces":["application/json"],"tags":["comments"],"summary":"List comments for a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true},{"type":"integer","description":"Page size","name":"limit","in":"query"},{"type":"integer","description":"Offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","schema":{"type":"object"}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["comments"],"summary":"Post a comment on a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true},{"description":"Comment body","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.CommentRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.Comment"}}}}},"/content/{id}/like":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["likes"],"summary":"Check whether the current user has liked a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.LikeStatusResponse"}}}},"post":{"security":[{"BearerAuth":[]}],"description":"Idempotent — liking an already-liked item is a no-op.","produces":["application/json"],"tags":["likes"],"summary":"Like a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}},"delete":{"security":[{"BearerAuth":[]}],"description":"Idempotent — unliking a non-liked item is a no-op.","produces":["application/json"],"tags":["likes"],"summary":"Unlike a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/content/{id}/likes/count":{"get":{"produces":["application/json"],"tags":["likes"],"summary":"Get the number of likes for a content item (public)","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.LikeCountResponse"}}}}},"/content/{id}/poster":{"get":{"description":"Returns 404 if no poster has been uploaded. No signature","produces":["application/octet-stream"],"tags":["content"],"summary":"Serve a content item's poster image (public)","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK"},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}},"post":{"security":[{"BearerAuth":[]}],"description":"Replaces any existing poster. Posters are served publicly","consumes":["multipart/form-data"],"produces":["application/json"],"tags":["content"],"summary":"Upload a poster image for a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true},{"type":"file","description":"Image file (jpg/png/webp)","name":"file","in":"formData","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Content"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/content/{id}/rating":{"get":{"produces":["application/json"],"tags":["ratings"],"summary":"Get rating stats for a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.RatingStatsResponse"}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["ratings"],"summary":"Rate a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true},{"description":"Rating payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.RateRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/content/{id}/renditions":{"get":{"produces":["application/json"],"tags":["content"],"summary":"List the HLS renditions emitted for a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/handler.RenditionInfo"}}}}}},"/content/{id}/tags":{"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["tags"],"summary":"Replace all tags for a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true},{"description":"Tag IDs","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.SetContentTagsRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/content/{id}/transcoding":{"get":{"produces":["application/json"],"tags":["content"],"summary":"Latest transcoder job for a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.TranscodingStatus"}}}}},"/content/{id}/upload":{"post":{"security":[{"BearerAuth":[]}],"description":"Streams the multipart upload to local storage and flips the item to \"ready\". Until the transcoder is wired up, the raw file is served directly via /media with a signed URL.","consumes":["multipart/form-data"],"produces":["application/json"],"tags":["content"],"summary":"Upload a source video file for a content item","parameters":[{"type":"string","description":"Content ID","name":"id","in":"path","required":true},{"type":"file","description":"Video file","name":"file","in":"formData","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Content"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/faqs":{"get":{"description":"Returns all active FAQs ordered by sort_order. Supports locale resolution via ?lang=uz|ru|en or Accept-Language header.","produces":["application/json"],"tags":["faq"],"summary":"List active FAQs","parameters":[{"type":"string","description":"Locale (uz|ru|en)","name":"lang","in":"query"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/handler.LocalizedFAQ"}}}}}},"/me/blocks":{"get":{"security":[{"BearerAuth":[]}],"description":"Returns a unified list of ContentListItems. Excludes episodes and series (only films/cartoons supported here). Pass `?lang=uz|ru|en` for localized strings.","produces":["application/json"],"tags":["blocks"],"summary":"List all content items blocked by the current user","parameters":[{"type":"integer","description":"Page size","name":"limit","in":"query"},{"type":"integer","description":"Offset","name":"offset","in":"query"},{"enum":["uz","ru","en"],"type":"string","description":"Resolve i18n fields to this locale","name":"lang","in":"query"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.LocalizedContentListResponse"}}}}},"/me/history":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["watch"],"summary":"List watch history for the authenticated viewer","parameters":[{"type":"integer","description":"Page size (default 20)","name":"limit","in":"query"},{"type":"integer","description":"Offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.HistoryListResponse"}}}}},"/me/likes":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["likes"],"summary":"List all content items liked by the current user","parameters":[{"type":"integer","description":"Page size","name":"limit","in":"query"},{"type":"integer","description":"Offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.LikesListResponse"}}}}},"/media/{path}":{"get":{"description":"Validates the HMAC signature + re-evaluates live parent rules on every request, so parents can revoke access in real time. Shared links without a valid (viewer, exp, sig) trio are rejected.","produces":["application/octet-stream"],"tags":["streaming"],"summary":"Serve a signed media asset","parameters":[{"enum":["user","child"],"type":"string","description":"viewer kind","name":"viewer","in":"query","required":true},{"type":"string","description":"viewer id (user_id or child_id)","name":"vid","in":"query","required":true},{"type":"string","description":"expiry unix seconds","name":"exp","in":"query","required":true},{"type":"string","description":"HMAC signature","name":"sig","in":"query","required":true},{"type":"string","description":"relative storage path","name":"path","in":"path","required":true}],"responses":{"200":{"description":"OK"},"403":{"description":"Forbidden","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/payments/click/card/request":{"post":{"security":[{"BearerAuth":[]}],"description":"Calls Click's POST /card_token/request. Click sends an SMS OTP to the phone linked to the card. Stores a pending (unverified) card and returns its ID. Follow up with POST /payments/click/card/verify.","consumes":["application/json"],"produces":["application/json"],"tags":["cards"],"summary":"Step 1 — request a Click card token","parameters":[{"description":"Card data","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ClickCardTokenRequestBody"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/service.CardTokenRequestResult"}}}}},"/payments/click/card/verify":{"post":{"security":[{"BearerAuth":[]}],"description":"Calls Click's POST /card_token/verify. On success the card is marked verified and ready for recurring charges.","consumes":["application/json"],"produces":["application/json"],"tags":["cards"],"summary":"Step 2 — verify card token with SMS OTP","parameters":[{"description":"OTP confirmation","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.ClickCardTokenVerifyBody"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Card"}}}}},"/payments/click/mock-pay":{"get":{"description":"Only available when CLICK_SECRET_KEY is empty. Flips a pending checkout to succeeded so you can test subscription activation without a real gateway.","produces":["application/json"],"tags":["billing"],"summary":"DEV ONLY — mark a pending Click transaction as paid","parameters":[{"type":"string","description":"provider_ref returned by /billing/checkout","name":"ref","in":"query","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Transaction"}}}}},"/payments/click/payment/{payment_id}/reversal":{"delete":{"security":[{"BearerAuth":[]}],"description":"Calls Click's DELETE /payment/reversal. Only payments from the current reporting month can be reversed. Also marks the local transaction as refunded.","produces":["application/json"],"tags":["billing"],"summary":"Reverse (refund) a Click payment","parameters":[{"type":"integer","description":"Click payment_id","name":"payment_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/payments/click/payment/{payment_id}/status":{"get":{"security":[{"BearerAuth":[]}],"description":"Calls Click's GET /payment/status/{service_id}/{payment_id}. Payment statuses: 0=created, 1=processing, 2=succeeded, <0=error.","produces":["application/json"],"tags":["billing"],"summary":"Check Click payment status","parameters":[{"type":"integer","description":"Click payment_id","name":"payment_id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/payment.ClickPaymentStatusResult"}}}}},"/payments/click/webhook":{"post":{"description":"Gateway callback — validates sign_string and updates the transaction + subscription.","consumes":["application/json"],"produces":["application/json"],"tags":["billing"],"summary":"Click webhook endpoint","responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/plans":{"get":{"produces":["application/json"],"tags":["plans"],"summary":"List subscription plans","parameters":[{"type":"boolean","description":"Only active (default true for public)","name":"only_active","in":"query"},{"enum":["uz","ru","en"],"type":"string","description":"Resolve i18n fields to this locale","name":"lang","in":"query"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.SubscriptionPlan"}}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["plans"],"summary":"Create a plan","parameters":[{"description":"Plan","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.PlanRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.SubscriptionPlan"}}}}},"/plans/{id}":{"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["plans"],"summary":"Update a plan","parameters":[{"type":"string","description":"Plan ID","name":"id","in":"path","required":true},{"description":"Plan","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.PlanRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.SubscriptionPlan"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["plans"],"summary":"Delete a plan","parameters":[{"type":"string","description":"Plan ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/recommendations":{"get":{"produces":["application/json"],"tags":["recommendations"],"summary":"List active recommendations (populated)","responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/service.PopulatedRecommendation"}}}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["recommendations"],"summary":"Create a recommendation slot","parameters":[{"description":"Recommendation payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.RecommendationRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.Recommendation"}}}}},"/recommendations/personalized":{"get":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["recommendations"],"summary":"Get personalized content recommendations based on watch history","parameters":[{"type":"integer","description":"Max results (default 20)","name":"limit","in":"query"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.Content"}}}}}},"/recommendations/{id}":{"put":{"security":[{"BearerAuth":[]}],"consumes":["application/json"],"produces":["application/json"],"tags":["recommendations"],"summary":"Update a recommendation slot","parameters":[{"type":"string","description":"Recommendation ID","name":"id","in":"path","required":true},{"description":"Recommendation payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.RecommendationRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Recommendation"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["recommendations"],"summary":"Delete a recommendation slot","parameters":[{"type":"string","description":"Recommendation ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/series":{"get":{"produces":["application/json"],"tags":["series"],"summary":"List all active series","responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.Series"}}}}},"post":{"security":[{"BearerAuth":[]}],"description":"`kind` must be \"seasons\" (episodes grouped by season) or \"episodes\" (flat list, e.g. Tom & Jerry). Defaults to \"episodes\" if omitted.","consumes":["application/json"],"produces":["application/json"],"tags":["series"],"summary":"Create a series","parameters":[{"description":"Series payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.SeriesRequest"}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/domain.Series"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}}},"/series/{id}":{"get":{"produces":["application/json"],"tags":["series"],"summary":"Get a series by ID","parameters":[{"type":"string","description":"Series ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Series"}}}},"put":{"security":[{"BearerAuth":[]}],"description":"`kind` controls episode display: \"seasons\" (grouped by season) or \"episodes\" (flat list).","consumes":["application/json"],"produces":["application/json"],"tags":["series"],"summary":"Update a series","parameters":[{"type":"string","description":"Series ID","name":"id","in":"path","required":true},{"description":"Series payload","name":"body","in":"body","required":true,"schema":{"$ref":"#/definitions/handler.SeriesRequest"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Series"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/handler.ErrorResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/handler.ErrorResponse"}}}},"delete":{"security":[{"BearerAuth":[]}],"produces":["application/json"],"tags":["series"],"summary":"Delete a series","parameters":[{"type":"string","description":"Series ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/handler.MessageResponse"}}}}},"/series/{id}/episodes":{"get":{"produces":["application/json"],"tags":["series"],"summary":"List episodes of a series ordered by season/episode number","parameters":[{"type":"string","description":"Series ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/domain.Content"}}}}}},"/series/{id}/poster":{"get":{"produces":["application/octet-stream"],"tags":["series"],"summary":"Serve a series poster image (public)","parameters":[{"type":"string","description":"Series ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK"}}},"post":{"security":[{"BearerAuth":[]}],"consumes":["multipart/form-data"],"produces":["application/json"],"tags":["series"],"summary":"Upload a poster for a series","parameters":[{"type":"string","description":"Series ID","name":"id","in":"path","required":true},{"type":"file","description":"Image file","name":"file","in":"formData","required":true}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/domain.Series"}}}}},"/stream/{id}/grant":{"get":{"security":[{"BearerAuth":[]}],"description":"Call this right before playback. The server checks the caller's subscription (or, for a child token, parent subscription + allow/deny rules) and returns a short-lived signed URL bound to the viewer's id. Hand the URL to your