API Endpoints

The RankHub API is a RESTful interface served by the SolidStart application. All endpoints are prefixed with /api.

Base URL: https://rankhub.app/api

Authentication

All endpoints (except public ones) require a valid JWT token sent as an Authorization: Bearer <token> header or as an auth cookie. See Authentication for details.

Matchups and Voting

Method	Endpoint	Auth	Description
GET	/v1/matchup	No	Get a matchup for a subcategory
POST	/v1/vote	Yes	Submit a vote between two items
GET	/v1/compare	Yes	Compare two specific items
GET	/v1/compare/suggest	Yes	Get comparison suggestions
GET	/v1/compare/random	No	Get a random comparison
GET	/v1/guess	Yes	Guess the ranking of an item
POST	/v1/challenge	Yes	Submit a ranking challenge

Leaderboards

Method	Endpoint	Auth	Description
GET	/v1/leaderboard/:slug	No	Get leaderboard for a subcategory
GET	/v1/categories	No	List all categories
GET	/v1/categories/:slug	No	Get a category and its subcategories
GET	/v1/subcategories/:slug	No	Get subcategory details

Items

Method	Endpoint	Auth	Description
GET	/v1/item/:slug	No	Get item details by slug
GET	/v1/items/:id	No	Get item details by ID
GET	/v1/items/:id/history	No	Get item rating history
POST	/v1/community/submit	Yes	Submit a new item for review

User

Method	Endpoint	Auth	Description
GET	/v1/auth/me	Yes	Get current user profile
GET	/v1/user/profile	Yes	Get detailed user profile
PUT	/v1/user/notification-preferences	Yes	Update notification preferences
GET	/v1/user/votes/export	Yes	Export user's vote history
DELETE	/v1/user/delete-account	Yes	Delete account and all data

Users (Public)

Method	Endpoint	Auth	Description
GET	/v1/users/:id	No	Get public user profile
GET	/v1/users/:id/votes	No	Get user's recent votes
GET	/v1/users/:id/followers	No	Get user's followers
GET	/v1/users/:id/following	No	Get users being followed
GET	/v1/users/:id/activity	No	Get user activity feed
GET	/v1/users/:id/achievements	No	Get user achievements
GET	/v1/users/:id/rating-history	No	Get user's rating history
POST	/v1/user/follow/:id	Yes	Follow/unfollow a user

Authentication

Method	Endpoint	Auth	Description
POST	/v1/auth/signup	No	Create a new account
POST	/v1/auth/signin	No	Sign in with email/password
POST	/v1/auth/signout	Yes	Sign out and clear session
POST	/v1/auth/verify-email	No	Verify email with token
POST	/v1/auth/send-verification	No	Resend verification email
POST	/v1/auth/forgot-password	No	Request password reset
POST	/v1/auth/reset-password	No	Reset password with token
GET	/v1/auth/google	No	Initiate Google OAuth (302 redirect)
GET	/v1/auth/google/callback	No	Google OAuth callback
GET	/v1/auth/github	No	Initiate GitHub OAuth (302 redirect)
GET	/v1/auth/github/callback	No	GitHub OAuth callback

Search and Discovery

Method	Endpoint	Auth	Description
GET	/v1/search	No	Search items and subcategories
GET	/v1/search/suggest	No	Search autocomplete suggestions
GET	/v1/discover/trending	No	Get trending items
GET	/v1/discover/popular-subcategories	No	Get popular subcategories
GET	/v1/discover/controversial	No	Get controversial matchups

Health

Method	Endpoint	Auth	Description
GET	/health/live	No	Liveness check
GET	/health/ready	No	Readiness check (DB connectivity)

Error Responses

All errors return a JSON body with a message field and an appropriate HTTP status code:

{
  "message": "Item not found",
  "error": "NOT_FOUND"
}

Common status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 429 (rate limited), 500 (internal error).

Tournaments

Method	Endpoint	Auth	Description
GET	/v1/tournaments	No	List tournaments (filter by ?status)
POST	/v1/tournaments	Yes	Create a tournament
GET	/v1/tournaments/:id	No	Get tournament detail with bracket
DELETE	/v1/tournaments/:id	Yes	Cancel a tournament
POST	/v1/tournaments/:id/start	Yes	Seed and activate bracket
POST	/v1/tournaments/:id/join	Yes	Add items to a draft tournament
GET	/v1/tournaments/:id/bracket	No	Get full bracket structure
POST	/v1/tournaments/:id/vote	Optional	Vote in a tournament match

Subscriptions

Method	Endpoint	Auth	Description
GET	/v1/subscriptions/plans	No	List available subscription plans
POST	/v1/subscriptions/checkout	Yes	Create a Stripe checkout session
GET	/v1/subscriptions/status	Yes	Get current subscription status

Referrals

Method	Endpoint	Auth	Description
GET	/v1/referral/code	Yes	Get or auto-generate referral code
GET	/v1/referral/stats	Yes	Get referral statistics
POST	/v1/referral/claim	Yes	Claim a referral during signup

Achievements

Method	Endpoint	Auth	Description
GET	/v1/achievements	No	List all achievement definitions
POST	/v1/achievements	Admin	Seed achievements into database

Embed

Method	Endpoint	Auth	Description
GET	/v1/embed/:slug	No	Get leaderboard embed widget JavaScript

Webhooks

Method	Endpoint	Auth	Description
POST	/v1/webhooks	Yes	Create a webhook subscription
GET	/v1/webhooks	Yes	List webhook subscriptions
DELETE	/v1/webhooks/:id	Yes	Delete a webhook subscription

API Keys

Method	Endpoint	Auth	Description
POST	/v1/api-keys	Yes	Create an API key
GET	/v1/api-keys	Yes	List API keys
DELETE	/v1/api-keys/:id	Yes	Revoke an API key

User Settings

Method	Endpoint	Auth	Description
GET	/v1/user/achievements	Yes	Get earned achievements and voting streak
GET	/v1/user/export	Yes	Full GDPR data export
GET	/v1/user/digest	Yes	Get weekly digest summary
PATCH	/v1/user/change-password	Yes	Change account password
GET	/v1/user/privacy	Yes	Get privacy settings
PUT	/v1/user/privacy	Yes	Update privacy settings
GET	/v1/user/notifications	Yes	List notifications (paginated)
PATCH	/v1/user/notifications/:id/read	Yes	Mark notification as read
POST	/v1/user/notifications/read-all	Yes	Mark all notifications as read

Push Notifications

Method	Endpoint	Auth	Description
GET	/v1/notifications/push	Yes	List registered push subscriptions
POST	/v1/notifications/push	Yes	Register a push subscription
DELETE	/v1/notifications/push	Yes	Remove a push subscription

Comments

Method	Endpoint	Auth	Description
GET	/v1/comments	No	List comments for an entity
POST	/v1/comments	Yes	Create a comment
PATCH	/v1/comments	Yes	Edit own comment
DELETE	/v1/comments	Yes	Delete own comment

Community

Method	Endpoint	Auth	Description
GET	/v1/community/top-voters	No	Get top 50 all-time voters

Cron (Internal, requires CRON_SECRET)

Method	Endpoint	Auth	Description
GET	/v1/cron/check-do-health	CRON_SECRET	Check DO worker health
GET	/v1/cron/evaluate-alerts	CRON_SECRET	Evaluate and dispatch alerts
GET	/v1/cron/streak-recovery	CRON_SECRET	Send streak recovery emails
GET	/v1/cron/send-digest	CRON_SECRET	Send weekly digest emails
GET	/v1/cron/rotate-challenge	CRON_SECRET	Rotate daily challenge

Admin

Method	Endpoint	Auth	Description
GET	/v1/admin/stats	Admin	Platform statistics
GET	/v1/admin/analytics	Admin	Detailed analytics metrics
GET	/v1/admin/challenge	Admin	Get/set daily challenge
POST	/v1/admin/challenge	Admin	Set daily challenge
GET	/v1/admin/email-digest	Admin	Generate weekly digest email HTML

CSP Reporting

Method	Endpoint	Auth	Description
POST	/v1/csp-report	No	Accept browser CSP violation reports