API Documentation

This document provides an overview of the API endpoints and their usage.

Note: The authentication and session management mechanisms rely on cookies for maintaining user sessions. Therefore, clients interacting with these endpoints should ensure they properly handle cookies (e.g., storing and sending them with each request) to maintain authenticated states throughout the session.

Authentication & Session Management

User Authentication

Get Email Verification Code

Description: Request a verification code to be sent to the user's email address.
Endpoint: POST /users/verification-code
Request Body:
```
{
  "email": "string"
}
```

Response:

Success: 200 OK

{
  "status": "success",
  "message": "Verification code sent successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid email address",
  "error": {
    "code": "INVALID_EMAIL"
  }
}

Error: 429 Too Many Requests

{
  "status": "error",
  "message": "Too many requests. Please try again later.",
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "details": {
      "nextRequestTime": 1620000000000
    }
  }
}

Error: 500 Internal Server Error

{
  "status": "error",
  "message": "Error sending verification code.",
  "error": {
    "code": "SEND_ERROR"
  }
}

Register User

Description: Register a new user account.
Endpoint: POST /users/register

Request Body:

{
  "email": "string",
  "password": "string",
  "username": "string",
  "code": 123456
}

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "username": "string",
    "email": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "gender": null,
      "location": "string",
      "birthday": null,
      "bio": "string",
      "avatar": "string",
      "customizeUrls": []
    },
    "experience": 0,
    "identity": [],
    "suspended": false,
    "_id": "string",
    "safetyRecords": [],
    "createdAt": "string",
    "updatedAt": "string"
  },
  "message": "User registered successfully."
}

The gender field is null if not specified, true is male, and false is female.
User will be logged in automatically after registration.

Error: 400 Bad Request

{
  "status": "error",
  "message": "All fields are required",
  "error": {
    "code": "MISSING_FIELDS",
    "details": {
      "email": "string",
      "password": "string",
      "username": "string",
      "code": 123456
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid verification code, please get a new one",
  "error": {
    "code": "INVALID_CODE"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Verification code expired",
  "error": {
    "code": "CODE_EXPIRED"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email does not match",
  "error": {
    "code": "EMAIL_MISMATCH"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Password must be at least 6 characters long",
  "error": {
    "code": "PASSWORD_TOO_SHORT"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username must be at least 3 characters long",
  "error": {
    "code": "USERNAME_TOO_SHORT"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username must be at most 20 characters long",
  "error": {
    "code": "USERNAME_TOO_LONG"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username must contain only letters, numbers, underscores, and hyphens",
  "error": {
    "code": "INVALID_USERNAME"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username contains inappropriate words",
  "error": {
    "code": "PROFANE_USERNAME"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid email address",
  "error": {
    "code": "INVALID_EMAIL"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email already in use",
  "error": {
    "code": "EMAIL_IN_USE"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username already in use",
  "error": {
    "code": "USERNAME_IN_USE"
  }
}

Error: 500 Internal Server Error

{
  "status": "error",
  "message": "Error registering user.",
  "error": {
    "code": "REGISTER_ERROR"
  }
}

Login User

Description: Log in an existing user account.
Endpoint: POST /users/login

Request Body:

{
  "identifier": "string",
  "password": "string"
}

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "username": "string",
    "email": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "gender": null,
      "location": "string",
      "birthday": null,
      "bio": "string",
      "avatar": "string",
      "customizeUrls": []
    },
    "experience": 0,
    "identity": [],
    "suspended": false,
    "_id": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "message": "User logged in successfully."
}

The message may vary if 2FA is required. (e.g., "User logged in successfully. 2FA required.")
The gender field is null if not specified, true is male, and false is female.

Error: 400 Bad Request

{
  "status": "error",
  "message": "All fields are required",
  "error": {
    "code": "MISSING_FIELDS",
    "details": {
      "identifier": "string",
      "password": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "User already logged in",
  "error": {
    "code": "ALREADY_LOGGED_IN"
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND"
  }
}

Error: 401 Unauthorized

{
  "status": "error",
  "message": "Invalid password",
  "error": {
    "code": "INVALID_PASSWORD"
  }
}

Error: 500 Internal Server Error

{
  "status": "error",
  "message": "Error logging in user",
  "error": {
    "code": "LOGIN_ERROR"
  }
}

Logout User

Description: Log out the current user. (Clears the session)
Endpoint: POST /users/logout

Response:

Success: 200 OK

{
  "status": "success",
  "message": "User logged out successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "User not logged in",
  "error": {
    "code": "NOT_LOGGED_IN"
  }
}

Two-Factor Authentication

Description: Verify the two-factor authentication code.
Endpoint: POST /users/2fa
Request Body:
```
{
  "code": 123456
}
```

Response:

Success: 200 OK

{
  "status": "success",
  "message": "User logged in successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "2FA not required",
  "error": {
    "code": "2FA_NOT_REQUIRED"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Verification code is required",
  "error": {
    "code": "NO_VERIFICATION_CODE"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "All fields are required",
  "error": {
    "code": "MISSING_FIELDS"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Verification code expired",
  "error": {
    "code": "CODE_EXPIRED"
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email does not match",
  "error": {
    "code": "EMAIL_MISMATCH"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid verification code, please get a new one",
  "error": {
    "code": "INVALID_CODE"
  }
}

Error: 401 Unauthorized

{
  "status": "error",
  "message": "User not logged in",
  "error": {
    "code": "NOT_LOGGED_IN"
  }
}

Error: 500 Internal Server Error

{
  "status": "error",
  "message": "Error logging in user",
  "error": {
    "code": "LOGIN_ERROR"
  }
}

Please get a verification code before attempting to log in (Two-Factor Authentication). Use the Get Email Verification Code endpoint.

Reset Password By Email

Description: Reset the user's password using their email address.
Endpoint: POST /users/reset-password-by-email

Request Body:

{
  "email": "string",
  "password": "string",
  "code": 123456
}

Response:

Success: 200 OK

{
  "status": "success",
  "message": "Password reset successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email verification code is required",
  "error": {
    "code": "NO_VERIFICATION_CODE"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email is required",
  "error": {
    "code": "MISSING_EMAIL",
    "details": {
      "email": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Verification code expired",
  "error": {
    "code": "CODE_EXPIRED"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email does not match",
  "error": {
    "code": "EMAIL_MISMATCH"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid verification code, please get a new one",
  "error": {
    "code": "INVALID_CODE"
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Password is required",
  "error": {
    "code": "MISSING_PASSWORD",
    "details": {
      "password": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Password must be at least 6 characters long",
  "error": {
    "code": "PASSWORD_TOO_SHORT"
  }
}

Error: 500 Internal Server Error

{
  "status": "error",
  "message": "Error updating user",
  "error": {
    "code": "UPDATE_ERROR"
  }
}

Please get a verification code before attempting to reset the password. Use the Get Email Verification Code endpoint.

Session Management

Get Current Session

Description: Get the current session status.
Endpoint: GET /sessions/current

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "authenticated": true,
    "twoFactorAuthenticated": true,
    "userId": "string",
    "sessionId": "string"
  },
  "message": "Current session status retrieved successfully."
}

Success: 200 OK

{
  "status": "success",
  "data": {
    "authenticated": true,
    "twoFactorAuthenticated": false,
    "userId": "string"
  },
  "message": "Current session status retrieved successfully."
}

Success: 200 OK

{
  "status": "success",
  "data": {
    "authenticated": false,
    "twoFactorAuthenticated": false,
    "userId": null
  },
  "message": "Current session status retrieved successfully."
}

Get All User Sessions

Description: Get all sessions for a user.
Endpoint: GET /sessions/user/:userId

Response:

Success: 200 OK

{
  "status": "success",
  "data": [
    {
      "sessionId": "string",
      "authenticated": true,
      "twoFactorAuthenticated": true,
      "userId": "string"
    }
  ],
  "message": "User sessions listed successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "User ID is required",
  "error": {
    "code": "MISSING_USER_ID",
    "details": {
      "userId": "string"
    }
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Delete Session

Description: Delete a specific session.
Endpoint: DELETE /sessions/:sessionId

Response:

Success: 200 OK

{
  "status": "success",
  "message": "Session deleted successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Session ID is required",
  "error": {
    "code": "MISSING_SESSION_ID",
    "details": {
      "sessionId": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Cannot delete the current session",
  "error": {
    "code": "CANNOT_DELETE_CURRENT_SESSION",
    "details": {
      "sessionId": "string"
    }
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Delete All Sessions (Except Current)

Description: Delete all sessions for the user except the current session.
Endpoint: DELETE /sessions/user/:userId/exclude-current

Response:

Success: 200 OK

{
  "status": "success",
  "message": "Sessions deleted successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "User ID is required",
  "error": {
    "code": "MISSING_USER_ID",
    "details": {
      "userId": "string"
    }
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Delete All Sessions Except One

Description: Delete all sessions for the user except one specified session.
Endpoint: DELETE /sessions/user/:userId/exclude/:excludeSessionId

Response:

Success: 200 OK

{
  "status": "success",
  "message": "Sessions deleted successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "User ID is required",
  "error": {
    "code": "MISSING_USER_ID",
    "details": {
      "userId": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Session ID is required",
  "error": {
    "code": "MISSING_SESSION_ID",
    "details": {
      "sessionId": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Cannot delete the current session",
  "error": {
    "code": "CANNOT_DELETE_CURRENT_SESSION",
    "details": {
      "sessionId": "string"
    }
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Delete All Sessions

Description: Delete all sessions for the user.
Endpoint: DELETE /sessions/user/:userId

Response:

Success: 200 OK

{
  "status": "success",
  "message": "Sessions deleted successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "User ID is required",
  "error": {
    "code": "MISSING_USER_ID",
    "details": {
      "userId": "string"
    }
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

User Management

User Information & Profile

Get User By ID

Description: Get user information by user ID.
Endpoint: GET /users/id/:id

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "_id": "string",
    "username": "string",
    "email": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "gender": null,
      "location": "string",
      "birthday": "string",
      "bio": "string",
      "avatar": "string",
      "customizeUrls": []
    },
    "experience": 0,
    "identity": []
  },
  "message": "User found successfully."
}

The email field is masked if the user is not the owner of the account.
The gender field is null if not specified, true is male, and false is female.

Error: 400 Bad Request

{
  "status": "error",
  "message": "User ID is required",
  "error": {
    "code": "MISSING_USER_ID",
    "details": {
      "userId": "string"
    }
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND",
    "details": {
      "userId": "string"
    }
  }
}

Get User By Username

Description: Get user information by username.
Endpoint: GET /users/username/:username

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "_id": "string",
    "username": "string",
    "email": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "gender": null,
      "location": "string",
      "birthday": "string",
      "bio": "string",
      "avatar": "string",
      "customizeUrls": []
    },
    "experience": 0,
    "identity": []
  },
  "message": "User found successfully."
}

The email field is masked if the user is not the owner of the account.
The gender field is null if not specified, true is male, and false is female.

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username is required",
  "error": {
    "code": "MISSING_USERNAME",
    "details": {
      "username": "string"
    }
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND",
    "details": {
      "username": "string"
    }
  }
}

Get User By Email

Description: Get user information by email.
Endpoint: GET /users/email/:email

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "_id": "string",
    "username": "string",
    "email": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "gender": null,
      "location": "string",
      "birthday": "string",
      "bio": "string",
      "avatar": "string",
      "customizeUrls": []
    },
    "experience": 0,
    "identity": []
  },
  "message": "User found successfully."
}

The gender field is null if not specified, true is male, and false is female.

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email is required",
  "error": {
    "code": "MISSING_EMAIL",
    "details": {
      "email": "string"
    }
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND",
    "details": {
      "email": "string"
    }
  }
}

Modify User Username

Description: Modify the username of the user.
Endpoint: PUT /users/:id/username
Request Body:
```
{
  "username": "string"
}
```

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "_id": "string",
    "username": "string",
    "email": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "gender": null,
      "location": "string",
      "birthday": "string",
      "bio": "string",
      "avatar": "string",
      "customizeUrls": []
    },
    "experience": 0,
    "identity": []
  },
  "message": "Username modified successfully."
}

The gender field is null if not specified, true is male, and false is female.

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username is required",
  "error": {
    "code": "MISSING_USERNAME",
    "details": {
      "username": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username must be at least 3 characters long",
  "error": {
    "code": "USERNAME_TOO_SHORT"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username must be at most 20 characters long",
  "error": {
    "code": "USERNAME_TOO_LONG"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username must contain only letters, numbers, underscores, and hyphens",
  "error": {
    "code": "INVALID_USERNAME"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username contains inappropriate words",
  "error": {
    "code": "PROFANE_USERNAME"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Username already in use",
  "error": {
    "code": "USERNAME_IN_USE"
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND",
    "details": {
      "userId": "string"
    }
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Modify User Email

Description: Modify the email of the user.
Endpoint: PUT /users/:id/email

Request Body:

{
  "email": "string",
  "code": 123456
}

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "_id": "string",
    "username": "string",
    "email": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "gender": null,
      "location": "string",
      "birthday": "string",
      "bio": "string",
      "avatar": "string",
      "customizeUrls": []
    },
    "experience": 0,
    "identity": []
  },
  "message": "Email modified successfully."
}

The gender field is null if not specified, true is male, and false is female.

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email is required",
  "error": {
    "code": "MISSING_EMAIL",
    "details": {
      "email": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email verification code is required",
  "error": {
    "code": "NO_VERIFICATION_CODE"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid verification code, please get a new one",
  "error": {
    "code": "INVALID_CODE"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Verification code expired",
  "error": {
    "code": "CODE_EXPIRED"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email does not match",
  "error": {
    "code": "EMAIL_MISMATCH"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid email address",
  "error": {
    "code": "INVALID_EMAIL"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Email already in use",
  "error": {
    "code": "EMAIL_IN_USE"
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND",
    "details": {
      "userId": "string"
    }
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Please get a verification code before attempting to modify the email. Use the Get Email Verification Code endpoint.

Modify User Profile

Description: Modify the profile of the user.
Endpoint: PUT /users/:id/profile
Request Body:
```
{
  "firstName": "string",
  "lastName": "string",
  "gender": null,
  "location": "string",
  "birthday": "string",
  "bio": "string",
  "avatar": "string",
  "customizeUrls": []
}
```
The firstName, lastName, location, bio, avatar, and customizeUrls fields are optional.
The gender field is null if not specified, true is male, and false is female.
The avatar field is a base64 encoded image. (size limit: 5MB)

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "_id": "string",
    "username": "string",
    "email": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "gender": null,
      "location": "string",
      "birthday": "string",
      "bio": "string",
      "avatar": "string",
      "customizeUrls": []
    },
    "experience": 0,
    "identity": []
  },
  "message": "Profile modified successfully."
}

The gender field is null if not specified, true is male, and false is female.

Error: 400 Bad Request

{
  "status": "error",
  "message": "First name is too long",
  "error": {
    "code": "FIRST_NAME_TOO_LONG"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Last name is too long",
  "error": {
    "code": "LAST_NAME_TOO_LONG"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Gender is invalid",
  "error": {
    "code": "GENDER_INVALID"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Location is too long",
  "error": {
    "code": "LOCATION_TOO_LONG"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Birthday is invalid",
  "error": {
    "code": "BIRTHDAY_INVALID"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Bio is too long",
  "error": {
    "code": "BIO_TOO_LONG"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Avatar is invalid",
  "error": {
    "code": "AVATAR_INVALID"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Avatar is too large",
  "error": {
    "code": "AVATAR_TOO_LARGE"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Customize URLs is invalid",
  "error": {
    "code": "CUSTOMIZE_URLS_INVALID"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Customize URLs are too long",
  "error": {
    "code": "CUSTOMIZE_URLS_TOO_LONG"
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND",
    "details": {
      "userId": "string"
    }
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Security

Modify User Password

Description: Modify the password of the user.
Endpoint: PUT /users/:id/password

Request Body:

{
  "currentPassword": "string",
  "newPassword": "string"
}

Response:

Success: 200 OK

{
  "status": "success",
  "message": "Password modified successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Current and new passwords are required",
  "error": {
    "code": "MISSING_PASSWORDS",
    "details": {
      "currentPassword": "string",
      "newPassword": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "New password must be at least 6 characters long",
  "error": {
    "code": "PASSWORD_TOO_SHORT"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "New password must be different from the current password",
  "error": {
    "code": "PASSWORD_SAME_AS_CURRENT"
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found",
  "error": {
    "code": "USER_NOT_FOUND"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Incorrect password",
  "error": {
    "code": "INCORRECT_PASSWORD"
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Get User Safety Records

Description: Get the safety records of the user.
Endpoint: GET /users/safety-records/:id
Request Query:
- startIndex: The start index of the safety records.
- limit: The number of safety records to return.

Response:

Success: 200 OK

{
  "status": "success",
  "data": [
    {
      "type": "string",
      "operationTime": "string",
      "ipAddress": "string",
      "device": "string"
    }
  ],
  "message": "Safety records found successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Start index is invalid",
  "error": {
    "code": "START_INDEX_INVALID"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Limit is invalid",
  "error": {
    "code": "LIMIT_INVALID"
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Limit is too large",
  "error": {
    "code": "LIMIT_TOO_LARGE"
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "Safety records not found",
  "error": {
    "code": "SAFETY_RECORDS_NOT_FOUND",
    "details": {
      "userId": "string"
    }
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "User not found or no safety records found",
  "error": {
    "code": "RECORDS_NOT_FOUND",
    "details": {
      "userId": "string"
    }
  }
}

Error: 500 Internal Server Error

{
  "status": "error",
  "message": "Error getting safety records",
  "error": {
    "code": "GET_ERROR"
  }
}

Error: 403 Forbidden

{
  "status": "error",
  "message": "Access denied",
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Safety records are automatically generated when the user logs in, 2FA, and changes their password.
Safety records will only show the last 100 records.

Game Management

Game Records

Get Game By ID

Description: Get the game data by game ID.
Endpoint: GET /games/:gameId

Response:

Success: 200 OK

{
  "status": "success",
  "data": {
    "_id": "string",
    "matchType": "string",
    "matchStatus": "string",
    "endTime": "string",
    "map": "string",
    "players": ["string"],
    "winners": ["string"],
    "operationRecords": [
      {
        "playerId": "string",
        "operationType": "string",
        "operationTime": "string",
        "operationDetails": {}
      }
    ]
  },
  "message": "Game found successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Game ID is required",
  "error": {
    "code": "MISSING_GAME_ID",
    "details": {
      "gameId": "string"
    }
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "Game not found",
  "error": {
    "code": "GAME_NOT_FOUND",
    "details": {
      "gameId": "string"
    }
  }
}

Get Games By User

Description: Get the games of the user.
Endpoint: GET /games/user/:userId
Request Query:
- page: The page number. (Default: 1)
- pageSize: The number of games to return per page. (Default: 10, Max: 30)

Response:

Success: 200 OK

{
  "status": "success",
  "data": [
    {
      "_id": "string",
      "matchType": "string",
      "matchStatus": "string",
      "endTime": "string",
      "map": "string",
      "players": ["string"],
      "winners": ["string"]
    }
  ],
  "message": "Games listed successfully."
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "User ID is required",
  "error": {
    "code": "MISSING_USER_ID",
    "details": {
      "userId": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid page number",
  "error": {
    "code": "INVALID_PAGE_NUMBER",
    "details": {
      "page": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Invalid page size",
  "error": {
    "code": "INVALID_PAGE_SIZE",
    "details": {
      "pageSize": "string"
    }
  }
}

Error: 400 Bad Request

{
  "status": "error",
  "message": "Page size too large",
  "error": {
    "code": "PAGE_SIZE_TOO_LARGE",
    "details": {
      "pageSize": "string"
    }
  }
}

Error: 404 Not Found

{
  "status": "error",
  "message": "Games not found",
  "error": {
    "code": "GAMES_NOT_FOUND",
    "details": {
      "userId": "string"
    }
  }
}

Leaderboard

Get Leaderboard

Description: Get the leaderboard. (Top 100)
Endpoint: GET /leaderboard

Response:

Success: 200 OK

{
  "status": "success",
  "data": [
    {
      "username": "string",
      "avatar": "string",
      "experience": 0
    }
  ],
  "message": "Leaderboard retrieved successfully."
}

The leaderboard only shows the top 100 users (only top 10 users have their avatars shown).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API_DOCUMENTATION.md

API_DOCUMENTATION.md

API Documentation

Table of Contents

Authentication & Session Management

User Authentication

Get Email Verification Code

Register User

Login User

Logout User

Two-Factor Authentication

Reset Password By Email

Session Management

Get Current Session

Get All User Sessions

Delete Session

Delete All Sessions (Except Current)

Delete All Sessions Except One

Delete All Sessions

User Management

User Information & Profile

Get User By ID

Get User By Username

Get User By Email

Modify User Username

Modify User Email

Modify User Profile

Security

Modify User Password

Get User Safety Records

Game Management

Game Records

Get Game By ID

Get Games By User

Leaderboard

Get Leaderboard

Files

API_DOCUMENTATION.md

Latest commit

History

API_DOCUMENTATION.md

File metadata and controls

API Documentation

Table of Contents

Authentication & Session Management

User Authentication

Get Email Verification Code

Register User

Login User

Logout User

Two-Factor Authentication

Reset Password By Email

Session Management

Get Current Session

Get All User Sessions

Delete Session

Delete All Sessions (Except Current)

Delete All Sessions Except One

Delete All Sessions

User Management

User Information & Profile

Get User By ID

Get User By Username

Get User By Email

Modify User Username

Modify User Email

Modify User Profile

Security

Modify User Password

Get User Safety Records

Game Management

Game Records

Get Game By ID

Get Games By User

Leaderboard

Get Leaderboard