âš¡
FeelFreak API v2.2.0|
Checklist ModelAdmin PanelLaunch App
RESTful Architecture Reference

FeelFreak Interactive Swagger API

Complete REST endpoint documentation for debates, polls, 1v1 battle arena, OpenAI topic generation, and gamification mechanics.

Base URL:
https://feelfreak.com/api
POST
/api/auth/register
Auth & Users
Register new Freak identity

Registers a new user account with initial +100 Freak Points bonus.

Request Body (JSON):
{
  "username": "neo_freak",
  "email": "neo@example.com",
  "password": "secure_password"
}
Response (200 OK):
{
  "success": true,
  "data": {
    "token": "jwt_token_here",
    "user": {
      "id": "u_123",
      "username": "neo_freak",
      "fp": 100
    }
  }
}
POST
/api/auth/login
Auth & Users
Authenticate existing user

Returns JWT bearer token and user profile state upon matching credentials.

Request Body (JSON):
{
  "usernameOrEmail": "neo_freak",
  "password": "secure_password"
}
Response (200 OK):
{
  "success": true,
  "data": {
    "token": "jwt_token_here",
    "user": {
      "id": "u_123",
      "username": "neo_freak"
    }
  }
}
GET
/api/auth/me
Auth & Users Auth Required
Get active session profile

Returns logged-in user profile, level, streak stats, follower counts, and active daily missions.

Response (200 OK):
{
  "success": true,
  "data": {
    "user": {
      "id": "u_123",
      "username": "neo_freak",
      "level": 3,
      "fp": 340,
      "followersCount": 42,
      "followingCount": 18
    }
  }
}
PATCH
/api/users/me
Auth & Users Auth Required
Update profile and @username

Updates bio, avatar, or @username (subject to 90-day cooldown constraint).

Request Body (JSON):
{
  "bio": "High-conviction debater and AI enthusiast.",
  "displayName": "Neo Freak"
}
Response (200 OK):
{
  "success": true,
  "data": {
    "message": "Profile updated successfully!"
  }
}
POST
/api/users/:targetUserId/follow
Social Graph Auth Required
1-Click Follow / Unfollow user

Toggles following state and awards +15 FP reward for active social engagement.

Parameters:
targetUserId (string)
Response (200 OK):
{
  "success": true,
  "data": {
    "isFollowing": true,
    "followersCount": 43,
    "fpEarned": 15
  }
}
POST
/api/streaks/checkin
Gamification Auth Required
24-hour daily streak check-in

Validates 20h–48h streak window and awards +25 FP with multiplier.

Response (200 OK):
{
  "success": true,
  "data": {
    "streakDays": 5,
    "fpReward": 25
  }
}
GET
/api/debates
Debates Arena
List active and resolved debates

Retrieves all debates with vote tallies, arguments counts, and categorized filters.

Response (200 OK):
{
  "success": true,
  "data": {
    "debates": [
      {
        "id": "deb_1",
        "title": "Booking.com vs MakeMyTrip: Which one is better?",
        "votesA": 142,
        "votesB": 98
      }
    ]
  }
}
POST
/api/debates/:id/vote
Debates Arena Auth Required
Vote on Side A or Side B

Cast stance vote on debate and calculate real-time percentage split (+15 FP).

Parameters:
id (string)
Request Body (JSON):
{
  "side": "A"
}
Response (200 OK):
{
  "success": true,
  "data": {
    "votesA": 143,
    "votesB": 98,
    "totalVotes": 241,
    "userVoted": "A"
  }
}
POST
/api/debates/:id/arguments
Debates Arena Auth Required
Submit steelmanned debate argument

Post structured PRO or CON reasoning (+25 FP).

Parameters:
id (string)
Request Body (JSON):
{
  "side": "PRO",
  "content": "Empirical pricing transparency completely favors Booking.com with zero hidden fees."
}
Response (200 OK):
{
  "success": true,
  "data": {
    "argumentId": "arg_99",
    "fpEarned": 25
  }
}
GET
/api/questions
Polls & Questions
List quick polls and daily question

Fetches active sentiment polls, option vote percentages, and total comments count.

Response (200 OK):
{
  "success": true,
  "data": {
    "questions": [
      {
        "id": "q_1",
        "title": "Zomato vs Swiggy: Which one is better in 2026?",
        "commentsCount": 78
      }
    ]
  }
}
GET
/api/questions/:id/comments
Polls & Questions
Get poll argument drawer comments

Retrieves all perspective arguments and nested replies for a specific poll.

Parameters:
id (string)
Response (200 OK):
{
  "success": true,
  "data": {
    "comments": [
      {
        "id": "comm_1",
        "authorUsername": "alex_trader",
        "content": "Swiggy Instamart is unbeatable for fast delivery.",
        "replies": []
      }
    ]
  }
}
POST
/api/questions/:id/comments
Polls & Questions Auth Required
Post argument comment on poll

Adds an argument perspective on the poll card (+10 FP).

Parameters:
id (string)
Request Body (JSON):
{
  "content": "Zomato Gold dining out discounts save significantly more on weekends."
}
Response (200 OK):
{
  "success": true,
  "data": {
    "commentId": "comm_102",
    "fpEarned": 10
  }
}
POST
/api/questions/:id/comments/:commentId/reply
Polls & Questions Auth Required
Reply / Counter a poll argument

Submits a nested counter-rebuttal to a specific poll argument.

Parameters:
id (string)commentId (string)
Request Body (JSON):
{
  "content": "That depends on the city tier; tier 2 cities have far better Swiggy coverage."
}
Response (200 OK):
{
  "success": true,
  "data": {
    "replyId": "rep_501"
  }
}
GET
/api/battles
1v1 Battle Arena
Fetch live 1v1 arena battles

Lists all active 1v1 duels with combatant cards, round steppers, and spectator voting counts.

Response (200 OK):
{
  "success": true,
  "data": {
    "battles": [
      {
        "id": "bat_1",
        "hostUsername": "sarah_ai",
        "challengerUsername": "marcus_dev",
        "status": "ACTIVE",
        "votesA": 55,
        "votesB": 42
      }
    ]
  }
}
POST
/api/battles
1v1 Battle Arena Auth Required
Issue direct 1v1 challenge to host

Challenges any post author to a direct 5-round battle (+50 FP & Host Floating Island Notification).

Request Body (JSON):
{
  "targetUserId": "u_882",
  "topic": "Is AI-generated code creating technical debt faster than solutions?"
}
Response (200 OK):
{
  "success": true,
  "data": {
    "battleId": "bat_999",
    "status": "PENDING"
  }
}
POST
/api/admin/automater/trigger
Automater & AI Auth Required
Trigger simulated bot activity cycle

Generates on-the-fly OpenAI topics, bot votes, and 50-200 arguments without touching real users.

Response (200 OK):
{
  "success": true,
  "data": {
    "message": "Automated post & interaction cycle executed successfully!"
  }
}