Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
564 lines (449 loc) · 9.97 KB

API_DOCUMENTATION.md

File metadata and controls

564 lines (449 loc) · 9.97 KB

API Documentation

This document provides comprehensive documentation for all API endpoints in the Club Management System.

Base URL

All API endpoints are relative to the application base URL.

Authentication

Most endpoints require authentication. The system uses Better Auth for authentication with session-based tokens.

Authentication Headers

  • Authorization: Bearer token (automatically handled by Better Auth)
  • Cookie: Session cookies (automatically managed)

Teams API

Create Team

Create a new team and become its leader.

Endpoint: POST /api/teams/create

Authentication: Required

Request Body:

{
  "name": "string (3-50 characters)"
}

Success Response (201):

{
  "team": {
    "id": "string",
    "name": "string",
    "joinCode": "string",
    "members": [],
    "teamleadId": "string",
    "teamleadName": "string",
    "points": 0,
    "isVerified": false,
    "createdAt": "ISO date string",
    "isTeamLead": true
  }
}

Error Responses:

  • 400: Invalid team name
  • 401: Unauthorized
  • 409: User already in a team
  • 500: Internal server error

Join Team

Join an existing team using a join code.

Endpoint: POST /api/teams/join

Authentication: Required

Request Body:

{
  "joinCode": "string (8 characters)"
}

Success Response (200):

{
  "message": "Successfully joined team"
}

Error Responses:

  • 400: Invalid join code or team is full
  • 401: Unauthorized
  • 404: Team not found
  • 409: User already in a team
  • 500: Internal server error

Leave Team

Leave the current team (for regular members only).

Endpoint: POST /api/teams/leave

Authentication: Required

Request Body: None

Success Response (200):

{
  "message": "Successfully left team"
}

Error Responses:

  • 400: Team lead cannot leave (must delete team)
  • 401: Unauthorized
  • 403: Cannot leave verified team
  • 404: User not in a team
  • 500: Internal server error

Delete Team

Delete an entire team (team leaders only).

Endpoint: POST /api/teams/delete

Authentication: Required (Team Leader only)

Request Body: None

Success Response (200):

{
  "message": "Team deleted successfully"
}

Error Responses:

  • 401: Unauthorized
  • 403: Cannot delete verified team
  • 404: User is not a team leader
  • 500: Internal server error

Get My Team

Get information about the current user's team.

Endpoint: GET /api/teams/my-team

Authentication: Required

Success Response (200):

{
  "team": {
    "id": "string",
    "name": "string",
    "joinCode": "string (only for team leaders)",
    "members": [
      {
        "id": "string",
        "name": "string",
        "email": "string"
      }
    ],
    "teamleadId": "string",
    "teamleadName": "string",
    "points": "number",
    "isVerified": "boolean",
    "createdAt": "ISO date string",
    "isTeamLead": "boolean"
  }
}

Response when not in a team (200):

{
  "team": null
}

Error Responses:

  • 401: Unauthorized
  • 500: Internal server error

Leaderboard API

Get Leaderboard

Get the ranked list of all verified teams.

Endpoint: GET /api/leaderboard

Authentication: Not required

Success Response (200):

[
  {
    "rank": 1,
    "id": "string",
    "name": "string",
    "points": 0
  }
]

Error Response (200 - graceful degradation):

[]

Questions API

Get Questions

Retrieve all available CTF challenges for the authenticated user's team.

Endpoint: GET /api/questions

Authentication: Required

Request Body: None

Requirements:

  • User must be authenticated
  • User must be a member of a verified team
  • Only verified teams can access challenges

Success Response (200):

{
  "questions": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "objective": "string (optional)",
      "notes": "string (optional)",
      "hints": ["string"],
      "points": "number",
      "category": "string",
      "resources": ["string"],
      "solved": "boolean"
    }
  ]
}

Response Fields:

  • id: Unique identifier for the question
  • title: Challenge title
  • description: Detailed challenge description
  • objective: Learning objective (optional)
  • notes: Additional notes (optional)
  • hints: Array of hint strings
  • points: Points awarded for solving
  • category: Challenge category (e.g., "Cryptography", "Web Security")
  • resources: Array of resource URLs
  • solved: Whether the user's team has solved this challenge

Error Responses:

  • 401: Unauthorized (user not logged in)
  • 404: Team not found or not verified
  • 500: Internal server error

Notes:

  • Only verified teams can access challenges
  • The solved field indicates if the user's current team has completed the challenge
  • Hints are provided as an array of strings
  • Resources are external links that may help with the challenge

Submit Answer

Submit an answer (flag) for a specific challenge.

Endpoint: POST /api/questions/submit

Authentication: Required

Request Body:

{
  "questionId": "string",
  "answer": "string"
}

Requirements:

  • User must be authenticated
  • User must be a member of a verified team
  • Question ID must exist
  • Answer must match the exact flag (case-sensitive)

Success Response (200):

{
  "success": true,
  "message": "Correct answer! Points awarded.",
  "points": 100
}

Error Responses:

  • 400: Invalid request, question already solved, or incorrect answer
  • 401: Unauthorized
  • 404: Team not found/not verified or question not found
  • 500: Internal server error

Admin API

List Users

Get a paginated list of all users (Admin only).

Endpoint: GET /api/admin/users

Authentication: Required (Admin)

Query Parameters:

  • page: number (default: 1)
  • limit: number (default: 10)
  • search: string (optional)
  • field: "email" | "name" (default: "email")

Success Response (200):

{
  "users": [
    {
      "id": "string",
      "name": "string",
      "email": "string",
      "image": "string",
      "emailVerified": "boolean",
      "banned": "boolean",
      "banReason": "string | null",
      "banExpires": "ISO date string | null",
      "createdAt": "ISO date string"
    }
  ],
  "total": 100,
  "page": 1,
  "limit": 10
}

Error Responses:

  • 401: Unauthorized
  • 403: Forbidden (not admin)
  • 500: Internal server error

Ban User

Ban a user from the system (Admin only).

Endpoint: POST /api/admin/users

Authentication: Required (Admin)

Request Body:

{
  "userId": "string",
  "banReason": "string",
  "banExpiresIn": "number (hours from now)"
}

Success Response (200):

{
  "message": "User banned successfully"
}

Error Responses:

  • 400: Invalid request data
  • 401: Unauthorized
  • 403: Forbidden (not admin)
  • 404: User not found
  • 500: Internal server error

Unban User

Remove ban from a user (Admin only).

Endpoint: DELETE /api/admin/users

Authentication: Required (Admin)

Request Body:

{
  "userId": "string"
}

Success Response (200):

{
  "message": "User unbanned successfully"
}

Error Responses:

  • 401: Unauthorized
  • 403: Forbidden (not admin)
  • 404: User not found
  • 500: Internal server error

List Teams

Get a list of all teams (Admin only).

Endpoint: GET /api/admin/teams

Authentication: Required (Admin)

Success Response (200):

{
  "teams": [
    {
      "id": "string",
      "name": "string",
      "joinCode": "string",
      "members": ["ObjectId"],
      "teamleadId": "ObjectId",
      "points": "number",
      "isVerified": "boolean",
      "createdAt": "ISO date string"
    }
  ]
}

Error Responses:

  • 401: Unauthorized
  • 403: Forbidden (not admin)
  • 500: Internal server error

Verify Team

Verify or unverify a team (Admin only).

Endpoint: POST /api/admin/teams/verify

Authentication: Required (Admin)

Request Body:

{
  "teamId": "string",
  "isVerified": "boolean"
}

Success Response (200):

{
  "message": "Team verification updated successfully"
}

Error Responses:

  • 400: Invalid request data
  • 401: Unauthorized
  • 403: Forbidden (not admin)
  • 404: Team not found
  • 500: Internal server error

Authentication API

The authentication API is handled by Better Auth and uses a catch-all route.

Endpoint: /api/auth/[...all]

This includes endpoints for:

  • Sign in/Sign up
  • Sign out
  • Password reset
  • Session management
  • OAuth providers

Refer to Better Auth documentation for detailed authentication API usage.

Error Response Format

All error responses follow this format:

{
  "error": "Error message description"
}

Rate Limiting

  • API endpoints may have rate limiting in place
  • Respect standard HTTP status codes for rate limiting (429)

Data Types

User Object

{
  id: string;
  name: string;
  email: string;
  image?: string;
  emailVerified: boolean;
  banned: boolean;
  banReason?: string | null;
  banExpires?: Date | null;
  createdAt: Date;
}

Team Object

{
  id: string;
  name: string;
  joinCode?: string;
  members: TeamMember[];
  teamleadId: string;
  teamleadName: string;
  points: number;
  isVerified: boolean;
  createdAt: string;
  isTeamLead: boolean;
}

Question Object

{
  id: string;
  title: string;
  description: string;
  objective?: string;
  notes?: string;
  hints: string[];
  points: number;
  category: string;
  resources: string[];
  solved: boolean;
}

Team Member Object

{
  id: string;
  name: string;
  email: string;
}

Status Codes

  • 200: Success
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 409: Conflict
  • 500: Internal Server Error

Last updated: January 9, 2026