{"swagger":"2.0","info":{"title":"story-bee","version":"0.38.9"},"definitions":{},"paths":{"/v1/audios/":{"post":{"summary":"Generate audio for a story","tags":["Audio"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"storyId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"voiceOption":{"anyOf":[{"type":"string","enum":["nova","echo","alloy","fable","onyx"]},{"type":"null"}]},"isShareable":{"type":"boolean","default":true},"voiceId":{"type":"string","default":null}},"required":["storyId"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/audios/{storyId}":{"get":{"summary":"Get story audio","tags":["Audio"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/audios/{storyId}/listen":{"get":{"summary":"Get story audio","tags":["Audio"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/contests/leader-board":{"get":{"summary":"Contest leader board","tags":["Contest"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":30,"default":10,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/contests/stories":{"get":{"summary":"List all the stories created during contest timeline","tags":["Contest"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"string","default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"},{"type":"string","default":"all","required":false,"in":"query","name":"genre"},{"type":"number","minimum":1,"maximum":60,"default":12,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/creator-partner-applications":{"post":{"summary":"Submit a creator partner application","tags":["Creator Partner Applications"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"anyOf":[{"type":"object","properties":{"instagramProfileUrl":{"type":"string"}},"required":["instagramProfileUrl"]},{"type":"object","properties":{"youtubeChannelUrl":{"type":"string"}},"required":["youtubeChannelUrl"]}],"properties":{"fullName":{"type":"string","minLength":2,"maxLength":100,"pattern":"^\\S(?:.*\\S)?$"},"email":{"type":"string","minLength":3,"maxLength":254,"pattern":"^\\S(?:.*\\S)?$","format":"email"},"instagramProfileUrl":{"type":"string","minLength":22,"maxLength":2048,"pattern":"^https:\\/\\/(?:www\\.)?instagram\\.com\\/[A-Za-z0-9._]{1,30}\\/?$"},"youtubeChannelUrl":{"type":"string","minLength":21,"maxLength":2048,"pattern":"^https:\\/\\/(?:www\\.)?youtube\\.com\\/(?:@[A-Za-z0-9._-]{1,100}|channel\\/[A-Za-z0-9_-]{1,100}|c\\/[A-Za-z0-9_-]{1,100}|user\\/[A-Za-z0-9_-]{1,100})\\/?$"},"audienceSize":{"type":"integer","minimum":0,"maximum":1000000000},"contentCategory":{"type":"string","minLength":2,"maxLength":100,"pattern":"^\\S(?:.*\\S)?$"},"country":{"type":"string","minLength":2,"maxLength":100,"pattern":"^\\S(?:.*\\S)?$"},"promotionPlans":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^\\S(?:.*\\S)?$"},"isSocialAccountActiveAndOwned":{"type":"boolean","enum":[true]}},"required":["fullName","email","audienceSize","contentCategory","country","promotionPlans","isSocialAccountActiveAndOwned"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/sb/stripe":{"post":{"summary":"Stripe Webhook","description":"Stripe Webhook endpoint","tags":["Stripe"],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/stories/all":{"get":{"summary":"List all public stories","tags":["Stories"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"string","default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"},{"type":"string","default":"all","required":false,"in":"query","name":"genre"},{"type":"number","minimum":1,"maximum":60,"default":9,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/stories/discover":{"get":{"summary":"Discover public stories with filters","description":"Filter public stories by genre, ageGroup, storyType, locale. Returns up to 20 newest.","tags":["Stories","Public"],"parameters":[{"type":"string","required":false,"in":"query","name":"genre"},{"type":"string","enum":["2-4","4-6","6-10","10-13"],"required":false,"in":"query","name":"ageGroup"},{"type":"string","enum":["chapter","long","edu","character","visual"],"required":false,"in":"query","name":"storyType"},{"type":"string","required":false,"in":"query","name":"locale"},{"type":"string","enum":["newest","oldest"],"default":"newest","required":false,"in":"query","name":"sort"},{"type":"number","minimum":1,"maximum":18,"default":18,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/stories/{slug}":{"get":{"summary":"Get story details by story Slug","tags":["Stories"],"parameters":[{"type":"string","pattern":"^[a-z0-9-]+[a-fA-F0-9]{24}$","required":true,"in":"path","name":"slug"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/stories/{storyId}/media":{"get":{"summary":"Get story images","tags":["Stories"],"parameters":[{"type":"boolean","default":true,"required":false,"in":"query","name":"isImage"},{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/stories/featured":{"post":{"summary":"List featured stories","tags":["Stories"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"storyIds":{"type":"array","default":[]},"limit":{"type":"number","minimum":1,"maximum":6,"default":6}}}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/report":{"post":{"summary":"Report Abuse","tags":["Stories"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"reason":{"type":"string","minLength":4},"message":{"type":"string","minLength":140}},"required":["email","reason","message"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/podcast.rss":{"get":{"summary":"List stories for podcast","tags":["Stories"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":60,"default":12,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/playlists/featured":{"get":{"summary":"List all featured playlists","tags":["Playlist","V2"],"parameters":[{"type":"number","default":1,"required":false,"in":"query","name":"page"},{"type":"string","default":"updatedAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"},{"type":"number","default":9,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/pub/playlists/{playlistId}":{"get":{"summary":"Get playlist details","tags":["Playlist","V2"],"parameters":[{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/unsub/{cid}/{userId}/fup":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/referrals/validate/{referralCode}":{"get":{"summary":"Check referral code is valid or not","description":"API to check referral code is valid or not","tags":["Referrals"],"parameters":[{"allOf":[{"type":"string","minLength":8},{"type":"string","maxLength":8}],"required":true,"in":"path","name":"referralCode"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/referrals/user/code":{"get":{"summary":"Get referral code of a user","description":"Get referral code of a user","tags":["Referrals"],"responses":{"200":{"description":"Default Response"}}}},"/v1/referrals":{"get":{"summary":"List all the referrals by a user","description":"List all the referrals by a user","tags":["Referrals"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stories/":{"post":{"summary":"Generate new story from API","tags":["Stories"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":400},"genre":{"type":"array","default":[]},"sceneCount":{"type":"number","enum":[0,4,6,10,16]},"imgStyle":{"type":"string"},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"voiceId":{"type":"string","default":null},"voiceOption":{"anyOf":[{"type":"string","enum":["nova","echo","alloy","fable","onyx"]},{"type":"null"}]},"provider":{"type":"string","enum":["openai","gemini","anyllm"],"default":"openai"},"replyLang":{"type":"string","enum":["Chinese","Spanish","English","Hindi","Arabic","Portuguese","German","French"],"default":"English"}},"required":["prompt"]}}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List all stories created by a user","tags":["Stories"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"string","default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"number","minimum":6,"maximum":60,"default":12,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stories/{storyId}":{"get":{"summary":"Get story details by story Id","tags":["Stories"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stories/single/{slug}":{"get":{"summary":"Get story details by story Slug","tags":["Stories"],"parameters":[{"type":"string","pattern":"^[a-z0-9-]+[a-fA-F0-9]{24}$","required":true,"in":"path","name":"slug"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stories/{storyId}/media":{"get":{"summary":"Get story images","tags":["Stories"],"parameters":[{"type":"boolean","default":true,"required":false,"in":"query","name":"isImage"},{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stories/{storyId}/visibility":{"patch":{"summary":"Update story visibility","tags":["Stories"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"isPublic":{"type":"boolean"}}}},{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stories/{slug}/enhance":{"put":{"summary":"Enhance story","tags":["Stories"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":400}},"required":["prompt"]}},{"type":"string","pattern":"^[a-z0-9-]+[a-fA-F0-9]{24}$","required":true,"in":"path","name":"slug"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stripe/checkout-session":{"post":{"summary":"Create checkout session","description":"Create checkout session for a user against a priceId","tags":["Stripe"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"priceId":{"type":"string","pattern":"price_[a-zA-Z0-9]{24}$"},"intro":{"type":"boolean","default":false},"project":{"type":"string","enum":["storybee","newsletter"]}},"required":["project"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stripe/portal":{"get":{"summary":"Create billing portal session","description":"Create billing portal session url of a loggedin in user","tags":["Stripe"],"responses":{"200":{"description":"Default Response"}}}},"/v1/stripe/invoices":{"get":{"summary":"Get stripe invoices","description":"Stripe invoices of a loggedin in user","tags":["Stripe"],"responses":{"200":{"description":"Default Response"}}}},"/v1/stripe/intro-eligibility":{"get":{"summary":"Get intro offer eligibility","description":"Whether the loggedin user can buy the introductory offer","tags":["Stripe"],"responses":{"200":{"description":"Default Response"}}}},"/v1/stripe/sync":{"post":{"summary":"Sync subscription","description":"Re-check the loggedin user intro subscription against Stripe, e.g. after checkout","tags":["Stripe"],"responses":{"200":{"description":"Default Response"}}}},"/v1/stripe/subscriptions":{"get":{"summary":"Get stripe subscriptions","description":"Stripe subscriptions of a loggedin in user","tags":["Stripe"],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/":{"post":{"summary":"Sign up a user","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","minLength":3,"maxLength":24},"project":{"type":"string","enum":["storybee","newsletter"]},"password":{"type":"string","pattern":"^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[#?!@$%^&*-]).{8,}$","minLength":8,"description":"Password must contain 1 small letter, 1 capital letter, 1 number and any one of following special characters `#?!@$%^&*-` and should have a minimum length of 8"},"referralCode":{"anyOf":[{"type":"string","minLength":8,"maxLength":8},{"type":"null"}]}},"required":["email","project","password"]}}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Edit user profile","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"anyOf":[{"type":"string","minLength":3,"maxLength":40},{"const":""}]},"contentPref":{"type":"object"},"shippingAddress":{"type":"object","properties":{"fullName":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"string"},"phone":{"type":"string"}}}}}}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete user profile","tags":["Users"],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/resend-verification":{"post":{"summary":"Resend email verification","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"email":{"type":"string","format":"email"},"project":{"type":"string","enum":["storybee","newsletter"]}},"required":["email","project"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/login":{"post":{"summary":"User log in","description":"If 2FA is enabled, accessToken is only valid for 1 day otherwise valid for 14 days","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"email":{"type":"string","format":"email"},"project":{"type":"string","enum":["storybee","newsletter"]}},"required":["email","project"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/validate":{"post":{"summary":"Validate OTP","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"userId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"otp":{"type":"string","minLength":6},"project":{"type":"string","enum":["storybee","newsletter"]}},"required":["userId","otp","project"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/reset-password":{"post":{"summary":"Reset password","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"password":{"type":"string","pattern":"^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[#?!@$%^&*-]).{8,}$","description":"Password must contain 1 small letter, 1 capital letter, 1 number and any one of following special characters `#?!@$%^&*-` and should have a minimum length of 8"},"userId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"otp":{"type":"string","minLength":6},"project":{"type":"string","enum":["storybee","newsletter"]}},"required":["password","userId","otp","project"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/forgot-password":{"post":{"summary":"Forgot password Email","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"email":{"type":"string","format":"email"},"project":{"type":"string","enum":["storybee","newsletter"]}},"required":["email","project"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/me":{"get":{"summary":"Get details of a logged in user","description":"Get details of a logged in user using cookie authentication","tags":["Users"],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/update-password":{"put":{"summary":"Update password","description":"API to update password from user profile","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"currentPsd":{"type":"string","pattern":"^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[#?!@$%^&*-]).{8,}$","description":"Password must contain 1 small letter, 1 capital letter, 1 number and any one of following special characters `#?!@$%^&*-` and should have a minimum length of 8"},"newPsd":{"type":"string","pattern":"^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[#?!@$%^&*-]).{8,}$","description":"Password must contain 1 small letter, 1 capital letter, 1 number and any one of following special characters `#?!@$%^&*-` and should have a minimum length of 8"}},"required":["currentPsd","newPsd"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/logout":{"post":{"summary":"Log out a user","description":"Log out and clear cookies from client","tags":["Users"],"responses":{"200":{"description":"Default Response"}}}},"/v1/users/email/validate":{"post":{"summary":"Check email is valid or not","description":"API to check email is valid or not","tags":["Users"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^[a-zA-Z0-9._%]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$"}},"required":["email"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/voices/add":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/voices/":{"get":{"summary":"List custom voices","description":"API to list custom voices","tags":["CustomVoices"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"string","default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/voices/{customVoiceId}":{"delete":{"summary":"Delete custom voices","description":"API to delete custom voices","tags":["CustomVoices"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"customVoiceId"}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Api to get custom voice","description":"Api to get custom voice details","tags":["CustomVoices"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"customVoiceId"}],"responses":{"200":{"description":"Default Response"}}}},"/v1/voices/narratives":{"get":{"summary":"Api to get narratives","description":"Api to get narratives","tags":["CustomVoices"],"responses":{"200":{"description":"Default Response"}}}},"/v1/vote/":{"post":{"summary":"Vote for a story","tags":["Votes"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"storyId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"voteValue":{"enum":[-1,1],"description":"1 for upvote and -1 for downvote"}},"required":["storyId","voteValue"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v1/vote/{storyId}":{"get":{"summary":"Count Votes of a story","tags":["Votes"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/books/":{"post":{"summary":"Create new book","tags":["Books","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":3,"maxLength":200},"description":{"type":"string","maxLength":1600,"default":""},"isPublic":{"type":"boolean","default":true},"price":{"type":"number","minimum":1,"maximum":100,"default":5},"currency":{"type":"string","enum":["usd","eur","aed"],"default":"usd"},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"isAdmin":{"type":"boolean","default":false},"book_cover_url":{"type":"string","format":"url"},"meta":{"type":"object"}},"required":["title","price","currency"]}}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List all books by user","tags":["Books","V2"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":100,"default":10,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["createdAt","title"],"default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/books/{bookId}":{"put":{"summary":"Update book details","tags":["Books","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"description":{"type":"string","maxLength":1600},"isPublic":{"type":"boolean"},"price":{"type":"object","properties":{"amount":{"type":"number","minimum":1,"maximum":100,"default":1},"currency":{"type":"string","default":"usd"}}},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"book_cover_url":{"type":"string","format":"url"},"meta":{"type":"object"}}}},{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Upsert book export variants (A4/A5)","description":"Partially updates export variant fields for A4 and/or A5. Each variant key is optional — only provided fields are $set. Use this to store PDF export URLs and dimensions after generation completes.","tags":["Books","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"exports":{"type":"object","additionalProperties":false,"properties":{"A4":{"type":"object","properties":{"contentUrl":{"type":"string","format":"url"},"coverUrl":{"type":"string","format":"url"},"backCoverUrl":{"type":"string","format":"url"},"contentWidthMm":{"type":"number"},"contentHeightMm":{"type":"number"},"numberOfPages":{"type":"number"}}},"A5":{"type":"object","properties":{"contentUrl":{"type":"string","format":"url"},"coverUrl":{"type":"string","format":"url"},"backCoverUrl":{"type":"string","format":"url"},"contentWidthMm":{"type":"number"},"contentHeightMm":{"type":"number"},"numberOfPages":{"type":"number"}}}}}}}},{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Get book details","tags":["Books","V2"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete book","tags":["Books","V2"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/books/{bookId}/json":{"get":{"summary":"Get book details","tags":["Books","V2"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Update book details","tags":["Books","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"description":{"type":"string","maxLength":1600},"isPublic":{"type":"boolean"},"price":{"type":"object","properties":{"amount":{"type":"number","minimum":1,"maximum":100,"default":1},"currency":{"type":"string","default":"usd"}}},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"book_cover_url":{"type":"string","format":"url"},"meta":{"type":"object"}}}},{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/books/{bookId}/toggle-publish":{"patch":{"summary":"Toggle book publish status (flip isPublic)","tags":["Books"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/books/{bookId}/magic/status":{"get":{"summary":"Get Generation status","tags":["Books","V2"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/books/{bookId}/magic":{"put":{"summary":"Create AI pages for book","tags":["Books","V2"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/characters/":{"post":{"summary":"Create new character","tags":["Characters","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":260},"description":{"type":"string","maxLength":1000},"image_url":{"type":"string","format":"url"},"meta":{"type":"object"}},"required":["name"]}}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List all characters by user","tags":["Characters","V2"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":100,"default":10,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["createdAt","name"],"default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/characters/{characterId}":{"put":{"summary":"Update character details","tags":["Characters","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":260},"description":{"type":"string","maxLength":1000},"image_url":{"type":"string","format":"url"},"meta":{"type":"object"}}}},{"type":"string","pattern":"^[0-9a-fA-F]{24}$","required":true,"in":"path","name":"characterId"}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Get character details","tags":["Characters","V2"],"parameters":[{"type":"string","pattern":"^[0-9a-fA-F]{24}$","required":true,"in":"path","name":"characterId"}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete character","tags":["Characters","V2"],"parameters":[{"type":"string","pattern":"^[0-9a-fA-F]{24}$","required":true,"in":"path","name":"characterId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/files/s3-sign":{"post":{"summary":"Get AWS signed request","tags":["Files","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"fileName":{"type":"string"},"uploadType":{"type":"string","enum":["user","albums","prompts","media","book","cover"],"default":"albums"},"fileType":{"type":"string","enum":["image/jpeg","image/jpg","image/png","image/svg","image/gif","application/pdf"],"default":"image/jpeg"},"eid":{"type":"string"}},"required":["fileName","fileType"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v2/files/unlink":{"delete":{"summary":"Unlink or delete a file from s3","tags":["Files","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"fileId":{"type":"string","description":"File name only in `folder/filename.ext` format"}},"required":["fileId"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v2/files/media-library":{"get":{"summary":"Get All the files uploaded by a user","tags":["Files","V2"],"responses":{"200":{"description":"Default Response"}}}},"/v2/orders/{orderId}":{"get":{"summary":"Get order details","tags":["Orders","V2"],"parameters":[{"type":"string","pattern":"^ord_[A-Z0-9]{12}$","required":true,"in":"path","name":"orderId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/orders/":{"get":{"summary":"List all orders by user","tags":["Orders","V2"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":100,"default":10,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/playlists/":{"post":{"summary":"Create new playlist","tags":["Playlist","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":60},"description":{"type":"string","minLength":16,"maxLength":600},"genre":{"type":"string","minLength":3,"maxLength":30},"visibility":{"type":"string","enum":["public","unlisted","private"],"default":"public"},"isPodcast":{"type":"boolean","default":false},"podcastImageUrl":{"anyOf":[{"type":"string","format":"url"},{"type":"null"}]}},"required":["name"]}}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Get playlist details","tags":["Playlist","V2"],"parameters":[{"type":"number","default":1,"required":false,"in":"query","name":"page"},{"type":"string","default":"updatedAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/playlists/{playlistId}/add":{"patch":{"summary":"Add or remove audio","tags":["Playlist","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"audioId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}}},{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/playlists/{playlistId}/remove":{"patch":{"summary":"Add or remove audio","tags":["Playlist","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"audioId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}}},{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/playlists/{playlistId}":{"put":{"summary":"Update playlist details","tags":["Playlist","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"audioId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}}}},{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Get playlist details","tags":["Playlist","V2"],"parameters":[{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete playlist","tags":["Playlist","V2"],"parameters":[{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/playlists/{playlistId}/podcast":{"get":{"summary":"Get podcast information","tags":["Playlist","V2"],"parameters":[{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/llmwh/{storyId}/{voiceInitiated}":{"post":{"summary":"Get story from fal.ai","tags":["Stories","Public","V2"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"},{"type":"string","enum":["yes","no"],"default":"no","required":true,"in":"path","name":"voiceInitiated"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/imgwh/{storyId}/{scene}/{userId}":{"post":{"summary":"Get story from fal.ai","tags":["Stories","Public","V2"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"},{"type":"string","enum":["yes","no"],"default":"no","required":true,"in":"path","name":"voiceInitiated"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/imgwhgenimi/{storyId}/{scene}/{userId}":{"post":{"summary":"Get story from fal.ai","tags":["Stories","Public","V2"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"},{"type":"string","enum":["yes","no"],"default":"no","required":true,"in":"path","name":"voiceInitiated"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/visionwh/{storyId}/{userId}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v2/avatarwh/{storyId}/{userId}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v2/avatarimgwh/{storyId}/{scene}/{userId}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v2/pub/books/storybee":{"get":{"summary":"List all books by admin","tags":["Books","V2","Public"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":100,"default":10,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["createdAt","title"],"default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/pub/books/featured":{"get":{"summary":"List featured books","tags":["Books","V2"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":100,"default":10,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["createdAt","title"],"default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/pub/books/user/{userId}":{"get":{"summary":"List all public by a user","tags":["Books","V2","Public"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":100,"default":10,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["createdAt","title"],"default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"},{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"userId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/pub/books":{"get":{"summary":"List all public by a user","tags":["Books","V2","Public"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":100,"default":10,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["createdAt","title"],"default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"},{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"userId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/pub/books/{bookId}":{"get":{"summary":"Get book details","tags":["Books","V2"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/prompts/random":{"get":{"summary":"Get random prompts","description":"Get one or more random prompts with optional filters","tags":["Prompts","V2"],"parameters":[{"type":"number","minimum":1,"maximum":10,"default":1,"required":false,"in":"query","name":"count"},{"type":"string","required":false,"in":"query","name":"category"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/stories/":{"post":{"summary":"Generate new story","tags":["Stories","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompt":{"type":"string","minLength":10,"maxLength":1200},"genre":{"type":"array","default":["Folk Tale"]},"sceneCount":{"type":"number","enum":[0,4,6,10,14,16]},"imgStyle":{"type":"string"},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"voiceId":{"type":"string","default":null},"voiceOption":{"anyOf":[{"type":"string","enum":["nova","echo","alloy","fable","onyx"]},{"type":"null"}]},"userImageUrl":{"anyOf":[{"type":"string","pattern":"^https://dw6bsvkxct6x8\\.cloudfront\\.net/.*$"},{"type":"string","pattern":"^https://.*\\.amazonaws\\.com/.*$"},{"type":"null"}]},"replyLang":{"type":"string","enum":["en-us","zh-cn","es-es","hi-in","ar-sa","pt-br","de-de","fr-fr","ml-in","ta-in","hy-am","fa-ir","bn-bd","ru-ru","id-id","ja-jp"],"default":"en-us"},"characters":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":600}},{"type":"null"}]},"setting":{"type":"string","maxLength":600}},"required":["prompt"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v2/stories/edu":{"post":{"summary":"Generate Edu story","tags":["Stories","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"prompt":{"type":"string","minLength":10,"maxLength":1200},"framework":{"type":"string","enum":["STEAM","STREAM","eSTEM","STEMM","STEM+C","SHAPE","MINT","SMILE","STREM","STEMIE"],"default":"STEAM"},"imgStyle":{"type":"string"},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"replyLang":{"type":"string","enum":["en-us","zh-cn","es-es","hi-in","ar-sa","pt-br","de-de","fr-fr","ml-in","ta-in","hy-am","fa-ir","bn-bd","ru-ru","id-id","ja-jp"],"default":"en-us"}},"required":["prompt","framework"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v2/stories/{storyId}":{"get":{"summary":"Get story details by story Id","tags":["Stories","V2"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/v2/{playlistId}/{podCastId}.rss":{"get":{"summary":"Get podcast details","tags":["Podcast","V2"],"parameters":[{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}}},"/v3/stories/":{"post":{"summary":"Generate new story","tags":["Stories","V3"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompt":{"type":"string","minLength":10,"maxLength":1200},"genre":{"type":"array","default":[]},"sceneCount":{"type":"number","enum":[0,4,6,10,14,16]},"imgStyle":{"type":"string"},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"voiceId":{"type":"string","default":null},"voiceOption":{"anyOf":[{"type":"string","enum":["nova","echo","alloy","fable","onyx"]},{"type":"null"}]},"replyLang":{"type":"string","enum":["en-us","zh-cn","es-es","hi-in","ar-sa","pt-br","de-de","fr-fr","ml-in","ta-in","hy-am","fa-ir","bn-bd","ru-ru","id-id","ja-jp"],"default":"en-us"},"characters":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":600}},{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","maxLength":600},"image_url":{"type":"string","format":"url"},"mask_url":{"type":"string","format":"url"}}}},{"type":"array","maxItems":0},{"type":"null"}]},"setting":{"type":"string","maxLength":600}},"required":["prompt"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v4/stories/":{"post":{"summary":"Generate new story with character","tags":["Stories","V4"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompt":{"type":"string","minLength":10,"maxLength":1200},"genre":{"type":"array","default":[]},"sceneCount":{"type":"number","enum":[0,4,6,10,14,16]},"imgStyle":{"type":"string"},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"replyLang":{"type":"string","enum":["en-us","zh-cn","es-es","hi-in","ar-sa","pt-br","de-de","fr-fr","ml-in","ta-in","hy-am","fa-ir","bn-bd","ru-ru","id-id","ja-jp"],"default":"en-us"},"setting":{"type":"string","maxLength":600},"characterId":{"type":"string"}},"required":["prompt","characterId"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/books/magic":{"post":{"summary":"Generate a book from user stories (v5, no LLM)","description":"Creates a new book container, builds page layout from user stories in pure JS, and returns the completed editorJson instantly. No AI calls, no polling. Max 50 pages per book.","tags":["Books","V5"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":1600,"default":""},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"isPublic":{"type":"boolean","default":true},"storyIds":{"type":"array","items":{"type":"string","minLength":1},"default":[]}},"required":["title"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/books/{bookId}":{"get":{"summary":"Get book details (v5)","tags":["Books","V5"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete book","tags":["Books","V2"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v5/books/{bookId}/toggle-publish":{"patch":{"summary":"Toggle book publish status (flip isPublic)","tags":["Books"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v5/books/{bookId}/clone":{"post":{"summary":"Clone a book (v5)","description":"Creates a duplicate of an existing book. Does not copy exports, book_cover_url, or meta. Limited to 3 clones per original book.","tags":["Books","V5"],"parameters":[{"type":"string","minLength":16,"maxLength":16,"required":true,"in":"path","name":"bookId"}],"responses":{"200":{"description":"Default Response"}}}},"/v5/characters/":{"post":{"summary":"Create new character or child profile","tags":["Characters","V5"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":260},"description":{"type":"string","maxLength":1000},"image_url":{"type":"string","format":"url"},"kind":{"type":"string","enum":["character","child"],"default":"character"},"interests":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":40}},"meta":{"type":"object"}},"required":["name"]}}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List all characters by user","tags":["Characters","V5"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":100,"default":10,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["createdAt","name"],"default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"},{"type":"string","enum":["character","child"],"required":false,"in":"query","name":"kind"}],"responses":{"200":{"description":"Default Response"}}}},"/v5/characters/{characterId}":{"put":{"summary":"Update character details","tags":["Characters","V5"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":260},"description":{"type":"string","maxLength":1000},"image_url":{"type":"string","format":"url"},"interests":{"type":"array","maxItems":10,"items":{"type":"string","minLength":1,"maxLength":40}},"meta":{"type":"object"}}}},{"type":"string","pattern":"^[0-9a-fA-F]{24}$","required":true,"in":"path","name":"characterId"}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Get character details","tags":["Characters","V5"],"parameters":[{"type":"string","pattern":"^[0-9a-fA-F]{24}$","required":true,"in":"path","name":"characterId"}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete character","tags":["Characters","V5"],"parameters":[{"type":"string","pattern":"^[0-9a-fA-F]{24}$","required":true,"in":"path","name":"characterId"}],"responses":{"200":{"description":"Default Response"}}}},"/v5/iap/apple":{"post":{"summary":"Apple IAP webhook","description":"App Store Server Notifications V2","tags":["IAP"],"parameters":[{"name":"body","in":"body","schema":{"type":"object","additionalProperties":false,"properties":{"signedPayload":{"type":"string","minLength":1},"userId":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},"required":["signedPayload"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/iap/google":{"post":{"summary":"Google Play webhook","description":"Real-time Developer Notifications via Pub/Sub","tags":["IAP"],"parameters":[{"name":"body","in":"body","schema":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"object"},"userId":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},"required":["message"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/iap/verify":{"post":{"summary":"App-initiated IAP verify","description":"Verify store purchase via Server API and activate instantly","tags":["IAP"],"parameters":[{"name":"body","in":"body","schema":{"type":"object","additionalProperties":false,"properties":{"store":{"type":"string","enum":["apple","google"]},"productId":{"type":"string","minLength":1},"transactionId":{"type":"string","minLength":1},"purchaseToken":{"type":"string","minLength":1},"jwsTransaction":{"type":"string","minLength":1}},"required":["store"],"allOf":[{"if":{"properties":{"store":{"enum":["apple"]}}},"then":{"anyOf":[{"required":["jwsTransaction"]},{"required":["transactionId"]}]}},{"if":{"properties":{"store":{"enum":["google"]}}},"then":{"required":["purchaseToken"]}}]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/prints/peecho/offerings":{"post":{"summary":"List available print product types","description":"Fetches available Peecho print product offerings (SOFTCOVER, HARDCOVER, LEAFLET) for the given country and currency. Results are cached in Redis for 5 days.","tags":["Print","Orders","V5"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"countryCode":{"type":"string"},"currency":{"type":"string"}},"required":["countryCode","currency"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/prints/peecho/qoute":{"post":{"summary":"Get pricing quote for a print order","description":"Retrieves a price quote from Peecho for a specific book, offering, quantity, export variant, and destination. Includes base price, per-page cost, shipping, VAT, and total. Results are cached in Redis for 24 hours. exportSize (A4/A5) determines which export PDF dimensions to use for page count.","tags":["Print","Orders","V5"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"bookId":{"type":"string","minLength":16,"maxLength":16},"quantity":{"type":"number","minimum":1,"maximum":10},"offeringId":{"type":"number"},"currency":{"type":"string","default":"USD"},"exportSize":{"type":"string","enum":["A4","A5"]},"shippingAddress":{"type":"object","properties":{"country":{"type":"string"},"state":{"type":"string"}},"required":["country"]}},"required":["bookId","quantity","offeringId"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/prints/peecho/order":{"post":{"summary":"Create print order and get Stripe checkout URL","description":"Creates a print order in the database with the given book, quantity, shipping address, export variant, and pricing quote. Returns a Stripe Checkout Session URL for payment. The order progresses to Peecho submission after successful Stripe payment via webhook. The exportSize field (A4/A5) selects which export PDF to use for printing.","tags":["Print","Orders","V5"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"bookId":{"type":"string","minLength":16,"maxLength":16},"quantity":{"type":"number","minimum":1,"maximum":10,"default":1},"currency":{"type":"string","default":"USD"},"exportSize":{"type":"string","enum":["A4","A5"]},"shippingAddress":{"type":"object","properties":{"fullName":{"type":"string"},"phone":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"}},"required":["fullName","phone","addressLine1","postalCode","city","state","country"]},"spineDetails":{"type":"object","properties":{"spineType":{"type":"string","enum":["dynamic","custom"],"default":"dynamic"},"textFont":{"type":"string","maxLength":50,"default":"Arial"},"textSize":{"type":"number","minimum":6,"maximum":72,"default":10},"textColour":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","default":"#77493f"},"textTop":{"type":"string","maxLength":200,"default":""},"textCenter":{"type":"string","maxLength":200,"default":""},"textBottom":{"type":"string","maxLength":200,"default":""},"customSpineUrl":{"type":"string","format":"url"}}},"quote":{"type":"object","properties":{"offering_id":{"type":"number"},"number_of_pages":{"type":"number"},"quantity":{"type":"number"},"country_code":{"type":"string"},"state":{"type":"string"},"base_price":{"type":"string"},"price_per_page":{"type":"string"},"total_product_price":{"type":"string"},"shipping_wholesale":{"type":"string"},"total_quantity_discount":{"type":"string"},"vat_percentage":{"type":"string"},"vat":{"type":"string"},"total_price":{"type":"string"},"currency":{"type":"string"},"exchange_rate":{"type":"string"}},"required":["total_price","currency"]}},"required":["bookId"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/prints/peecho/webhook":{"post":{"summary":"Receive Peecho order status updates","description":"Webhook endpoint called by Peecho whenever the status of a print order changes. Updates the internal order status, tracking information, and handles cancellation/refund flows.","tags":["Print","Orders","V5"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"signature":{"type":"string"},"order_id":{"type":"string"},"order_reference":{"type":"string"},"old_status":{"type":"string"},"new_status":{"type":"string"},"tracking_code":{"type":"string"},"tracking_url":{"type":"string"}},"required":["order_id","order_reference","new_status"]}}],"responses":{"200":{"description":"Default Response"}}}},"/v5/llmwh/{storyId}/{voiceInitiated}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v5/imgwh/{storyId}/{scene}/{userId}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v5/txt2imgwh/{storyId}/{scene}/{userId}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v5/charimgwh/{storyId}/{scene}/{userId}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v5/visionwh/{storyId}/{userId}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v5/avatarwh/{storyId}/{userId}":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v5/pub/stories/search":{"get":{"summary":"Search public stories by text","description":"Full-text search over public stories. Matches title, summary, prompt and content with relevance scoring. Supports pagination.","tags":["Stories","Public"],"parameters":[{"type":"string","minLength":2,"maxLength":100,"required":true,"in":"query","name":"q"},{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":1,"maximum":50,"default":18,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/v5/referrals/user/code":{"get":{"summary":"Get referral code of a user","description":"Get referral code of a user","tags":["Referrals"],"responses":{"200":{"description":"Default Response"}}}},"/v5/referrals":{"get":{"summary":"List all the referrals by a user","description":"List all the referrals by a user","tags":["Referrals"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"}],"responses":{"200":{"description":"Default Response"}}}},"/v5/stories/":{"post":{"summary":"Generate new story (v5 unified)","tags":["Stories","V5"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"storyType":{"type":"string","enum":["chapter","long","edu","character","visual"]},"prompt":{"type":"string","minLength":3,"maxLength":1200},"ageGroup":{"type":"string","enum":["2-4","4-6","6-10","10-13"],"default":"2-4"},"replyLang":{"type":"string","enum":["en-us","zh-cn","es-es","hi-in","ar-sa","pt-br","de-de","fr-fr","ml-in","ta-in","hy-am","fa-ir","bn-bd","ru-ru","id-id","ja-jp"],"default":"en-us"},"imgStyle":{"type":"string"},"genre":{"type":"array","default":[]},"sceneCount":{"type":"number","enum":[0,4,6,10,14,16]},"voiceOption":{"anyOf":[{"type":"string"},{"type":"null"}]},"voiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"characters":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":600}},{"type":"null"}]},"setting":{"type":"string","maxLength":600},"framework":{"type":"string"},"userImageUrl":{"type":"string"}},"required":["storyType","prompt"],"if":{"properties":{"storyType":{"enum":["edu"]}}},"then":{"properties":{"framework":{"type":"string","minLength":1,"enum":["STEAM","STREAM","eSTEM","STEMM","STEM+C","SHAPE","MINT","SMILE","STREM","STEMIE"]}},"required":["framework"]},"else":{"if":{"properties":{"storyType":{"enum":["visual"]}}},"then":{"properties":{"userImageUrl":{"type":"string","format":"url","minLength":1}},"required":["userImageUrl"]},"else":{"if":{"properties":{"storyType":{"enum":["character"]}}},"then":{"properties":{"sceneCount":{"type":"number"}},"required":["sceneCount"]},"else":{}}}}}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List user stories (v5)","tags":["Stories","V5"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"number","minimum":6,"maximum":60,"default":12,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"}],"responses":{"200":{"description":"Default Response"}}}},"/v5/stories/{storyId}":{"get":{"summary":"Get story details by story Id","tags":["Stories","V5"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"storyId"}],"responses":{"200":{"description":"Default Response"}}}},"/admin/creator-partner-applications/":{"get":{"summary":"List creator partner applications","tags":["Creator Partner Applications","Admin"],"parameters":[{"type":"integer","minimum":1,"maximum":100000,"default":1,"required":false,"in":"query","name":"page"},{"type":"integer","minimum":1,"maximum":100,"default":20,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["under_review","approved","rejected"],"required":false,"in":"query","name":"reviewStatus"},{"type":"string","minLength":2,"maxLength":100,"pattern":"^\\S(?:.*\\S)?$","required":false,"in":"query","name":"search"}],"responses":{"200":{"description":"Default Response"}}}},"/admin/creator-partner-applications/{applicationId}":{"get":{"summary":"Get a creator partner application","tags":["Creator Partner Applications","Admin"],"parameters":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"applicationId"}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Review a creator partner application","tags":["Creator Partner Applications","Admin"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"minProperties":1,"properties":{"reviewStatus":{"type":"string","enum":["under_review","approved","rejected"]},"reviewNotes":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^\\S(?:.*\\S)?$"}}}},{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"applicationId"}],"responses":{"200":{"description":"Default Response"}}}},"/admin/referral-commissions/":{"get":{"summary":"List creators with accumulated commission for payout review","description":"Admin dashboard for reviewing referral commission payouts","tags":["Referral Commissions","Admin"],"parameters":[{"type":"integer","minimum":1,"maximum":100000,"default":1,"required":false,"in":"query","name":"page"},{"type":"integer","minimum":1,"maximum":100,"default":20,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["true","false","all"],"default":"all","required":false,"in":"query","name":"settled"}],"responses":{"200":{"description":"Default Response"}}}},"/admin/referral-commissions/{referrerId}":{"get":{"summary":"Get commission detail for a specific creator","description":"Individual commission records for a referrer","tags":["Referral Commissions","Admin"],"parameters":[{"type":"integer","minimum":1,"maximum":100000,"default":1,"required":false,"in":"query","name":"page"},{"type":"integer","minimum":1,"maximum":100,"default":20,"required":false,"in":"query","name":"limit"},{"type":"string","enum":["true","false","all"],"default":"all","required":false,"in":"query","name":"settled"},{"type":"string","pattern":"^\\d{4}-\\d{2}$","required":false,"in":"query","name":"month"},{"type":"string","pattern":"^[a-fA-F0-9]{24}$","required":true,"in":"path","name":"referrerId"}],"responses":{"200":{"description":"Default Response"}}}},"/admin/referral-commissions/settle":{"patch":{"summary":"Mark commissions as settled/paid","description":"Batch mark referral commissions as paid out to creators","tags":["Referral Commissions","Admin"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"commissionIds":{"type":"array","items":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"minItems":1,"maxItems":500}},"required":["commissionIds"]}}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/generate":{"post":{"summary":"Admin api for testing","description":"Admin endpoint requires additional parameters, contact developers","tags":["StoryBee Admin"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompt":{"type":"string"},"isGenerateImage":{"type":"boolean","default":false}},"required":["prompt"]}}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/story/visbility":{"post":{"summary":"Admin api for story publish","description":"Admin endpoint requires additional parameters, contact developers","tags":["StoryBee Admin"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"storyId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"isPublish":{"type":"boolean","default":true}},"required":["storyId"]}}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/stories":{"get":{"summary":"Admin api for story publish","description":"Admin endpoint requires additional parameters, contact developers","tags":["StoryBee Admin"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"string","default":"createdAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"},{"type":"string","default":"all","required":false,"in":"query","name":"genre"},{"type":"number","minimum":1,"default":12,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/marketing/{count}":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/tts":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/redis/add-field":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/plans/inform":{"post":{"summary":"Email user about custom plan","description":"Email user about custom plan details","tags":["StoryBee Admin"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"email":{"type":"string","format":"email"},"planName":{"type":"string","enum":["free","base","voice","pro","hive","custom"],"default":"custom"},"planDetails":{"type":"object","properties":{"audios_count":{"type":"number"},"custom_voices":{"type":"number"},"descr_length":{"type":"number"},"plan_name":{"type":"string","default":"custom"},"podcast_count":{"type":"number"},"prompt_length":{"type":"number"},"scenes_count":{"type":"number"},"stories_count":{"type":"number"},"story_length":{"type":"number"},"books_count":{"type":"number"},"price":{"type":"number","multipleOf":0.01},"recurring":{"type":"object","properties":{"interval":{"type":"string","enum":["day","month","week","year"],"default":"month"},"interval_count":{"type":"number","default":1}}}}}},"required":["email","planName"]}}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/plans":{"put":{"summary":"Update plan ","description":"Admin endpoint to update user plan details","tags":["StoryBee Admin"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"email":{"type":"string","format":"email"},"planName":{"type":"string","enum":["free","base","voice","pro","hive","custom"]},"planDetails":{"type":"object","properties":{"audios_count":{"type":"number"},"custom_voices":{"type":"number"},"descr_length":{"type":"number"},"plan_name":{"type":"string","default":"custom"},"podcast_count":{"type":"number"},"prompt_length":{"type":"number"},"scenes_count":{"type":"number"},"stories_count":{"type":"number"},"story_length":{"type":"number"},"books_count":{"type":"number"},"price":{"type":"number","multipleOf":0.01}}}},"required":["email","planName"]}}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/playlists":{"get":{"summary":"List all playlists ","description":"Admin endpoint to list all playlists","tags":["StoryBee Admin"],"parameters":[{"type":"number","minimum":1,"default":1,"required":false,"in":"query","name":"page"},{"type":"string","default":"updatedAt","required":false,"in":"query","name":"sortBy"},{"type":"string","enum":["asc","desc"],"default":"desc","required":false,"in":"query","name":"sortOrder"},{"type":"number","minimum":1,"default":12,"required":false,"in":"query","name":"limit"}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/playlists/{playlistId}":{"get":{"summary":"Get playlist details","description":"Admin endpoint to get playlist details","tags":["StoryBee Admin"],"parameters":[{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Feature playlist","description":"Admin endpoint to update isFeatured status","tags":["StoryBee Admin"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"isFeatured":{"type":"boolean","default":false}}}},{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/prompts/bulk":{"post":{"summary":"Bulk insert prompts","description":"Admin endpoint to insert multiple prompts","tags":["StoryBee Admin","Prompts","V2"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"prompts":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string"},"genre":{"type":"string"},"sceneCount":{"type":"number"},"imgStyle":{"type":"string"},"ageGroup":{"type":"string"},"replyLang":{"type":"string"},"characters":{"type":"array","items":{"type":"string"}},"setting":{"type":"string"}},"required":["prompt","genre","sceneCount","imgStyle","ageGroup","replyLang","characters","setting"]},"minItems":1}},"required":["prompts"]}}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/email/storybee-one-time":{"post":{"summary":"Send one-time StoryBee email","description":"Preview or queue the one-time StoryBee marketing email for eligible users","tags":["StoryBee Admin","Email"],"parameters":[{"name":"body","in":"body","schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"dryRun":{"type":"boolean","default":true},"batchSize":{"type":"number","minimum":1,"maximum":200,"default":50},"delayMs":{"type":"number","minimum":200,"maximum":10000,"default":2000}}}}],"responses":{"200":{"description":"Default Response"}}}},"/admin/storybee/email-test":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/{playlistId}/{podCastId}.rss":{"get":{"summary":"Get podcast details","tags":["Podcast","V2"],"parameters":[{"type":"string","maxLength":12,"required":true,"in":"path","name":"playlistId"}],"responses":{"200":{"description":"Default Response"}}}}},"host":"0.0.0.0:3001","schemes":["http","https"],"basePath":"/api","consumes":["application/json"],"produces":["application/json"],"securityDefinitions":{"Bearer":{"type":"apiKey","in":"header","scheme":"bearer","name":"Authorization","bearerFormat":"JWT"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"token"}}}