API Reference

All API routes are under /api/. Authentication endpoints are managed by Better Auth; application endpoints are under /api/v1/.

Authentication

Method	Endpoint	Description
*	/api/auth/[...all]	Better Auth catch-all (sign-in, sign-up, OAuth, sessions, etc.)

Readings

Method	Endpoint	Description
POST	/api/v1/readings	Create a new tarot reading (enqueues BullMQ job)
GET	/api/v1/readings/can-play	Check if user can start a reading (credit/limit check)

Chat

Method	Endpoint	Description
POST	/api/v1/chats/[chatId]	Send a follow-up message in a reading chat

Credits

Method	Endpoint	Description
POST	/api/v1/credits/purchase	Purchase a credit pack (creates Stripe checkout session)

Spreads and Questions

Method	Endpoint	Description
GET	/api/v1/spreads	List all available tarot spreads
GET	/api/v1/questions/sample	Get sample questions for a category
GET	/api/v1/spread-questions/sample	Get sample questions for a specific spread

Tarot Readers

Method	Endpoint	Description
GET	/api/v1/tarot-readers	List all available tarot readers

Card of the Day

Method	Endpoint	Description
GET	/api/v1/card-of-day	Get today's Card of the Day entry
POST	/api/v1/card-of-day	Complete Card of the Day (awards credits)

Card Skins

Method	Endpoint	Description
GET	/api/v1/card-skins	List all card skins with ownership status

Guidance (Insights)

Method	Endpoint	Description
POST	/api/v1/guidance/weekly	Generate weekly guidance (enqueues async job)
POST	/api/v1/guidance/soul-journey	Generate/refresh Soul Journey (enqueues async job)

Text-to-Speech

Method	Endpoint	Description
GET	/api/v1/tts	Synthesize speech for a chat message (cached in R2)

AI Memory

Method	Endpoint	Description
GET	/api/v1/memory	Get user's AI memory facts

Notifications

Method	Endpoint	Description
GET	/api/v1/notifications	List notifications (paginated, filterable by category)
POST	/api/v1/notifications/[id]/read	Mark a notification as read
POST	/api/v1/notifications/read-all	Mark all notifications as read
GET	/api/v1/notifications/unread-count	Get unread notification count

Invitations

Method	Endpoint	Description
GET	/api/v1/invitations/summary	Get user's invitation stats and code
GET	/api/v1/invitations/invitees	List invited users and their status

Membership

Method	Endpoint	Description
GET	/api/v1/membership/billing	Get subscription and billing info

Feedback

Method	Endpoint	Description
POST	/api/v1/feedback	Submit user feedback with optional screenshots

Analytics

Method	Endpoint	Description
POST	/api/v1/analytics/events	Track analytics events
POST	/api/track-pageview	Record a page view (visitor cookie)

User Profile

Method	Endpoint	Description
GET	/api/v1/app/profile	Get current user's personal profile
PUT	/api/v1/app/profile	Update current user's personal profile
POST	/api/me/avatar	Upload user avatar
POST	/api/v1/app/delete-account	Initiate account deletion

Admin

Method	Endpoint	Description
POST	/api/admin/upload	Upload files (images, assets)
POST	/api/admin/translate	AI-powered content translation

Internal (Telegram Bot)

Protected by INTERNAL_API_KEY header. Not for external use.

Method	Endpoint	Description
POST	/api/v1/internal/readings/create	Create reading from Telegram bot

Download

Method	Endpoint	Description
GET	/api/download	Download reading share images