APIs - HackMD

--- title: APIs --- # APIs API routes and their descriptions ## Auth Module - Endpoint: `/api/v1/auth` - `/login` - POST - `/logout` - GET - `/register` - POST - `/verify-otp` - POST - `/send-otp` - GET - `/reset` - PATCH - `/checkin` - PUT ## Organizer Modules * Endpoint: `/api/v1/organizer` ### 1. Create Organizer Endpoint: **POST** `/` Request Body: ```jsonld { "email": "testorg@melinia.edu", "ph_no": "9876543210", "password": "securePassword123" } ``` Response Body: ```json { "status": true, "data": { "id": "MLNU40E8VB", "email": "testorg@melinia.edu", "ph_no": "9876543210", "role": "ORGANIZER", "created_at": "2026-01-18T16:31:20.156Z", "updated_at": "2026-01-18T16:31:20.156Z", "profile_completed": false, "payment_status": "EXEMPTED" } } ``` ### 2. Complete Organizer Profile Endpoint: **POST** `/profile` Request Body: ```jsonld { "user_id": "MLNUPI93F0", "first_name": "Suresh", "last_name": "Kumar", "college": "Coimbatore Institute of Technology", "degree": "B.E. Computer Science", "year": 3, "ph_no": "9876543210" } ``` Response Body: ```json { "status": true, "data": { "first_name": "Suresh", "last_name": "Kumar", "college": "Coimbatore Institute of Technology", "degree": "B.E. Computer Science", "year": 3, "created_at": "2026-01-18T16:33:03.208Z", "updated_at": "2026-01-18T16:33:03.208Z" } } ``` ## Team Management * Endpoint: `/api/v1/team` ### 1. Create Team Endpoint: **POST** `/api/v1/teams` Request Body: ```jsonld { "name":"Team-1", "member_emails":["kottesh@gmail.com", "pranav@melinia.in"] } ``` Response Body: ```json { "status": true, "message": "Team Creation Success", "data": {} } ``` ### 2. Get Team Details Endpoint: **GET** `/api/v1/teams/:team_id` Response Body: ```json {{ "status": true, "message": "List of all teams for this user", "data": [ { "id": "MLNT83MW9Q", "team_name": "Team-1", "event_id": null, "event_name": null, "leader_id": "MLNUVS262W", "member_count": "1" }, ] } ``` ### 3. Update Team details Endpoint: **PUT** `/api/v1/teams/:team_id` Request Body: ```json { "name":"End 2 End" }``` Response Body ```json { "status": true, "message": "Team updated successfully", "data": {} } ``` ### 4. Delete Team Endpoint: **DELTE** `/api/v1/teams/:team_id` Response Body: ```json { "status": true, "message": "Team Deleted Successfully!", "data": {} } ``` ### 5. Delete Team member Endpoint: **DELETE** `/api/v1/teams/:team_id/team_member/:member_id` Response Body: ```json { "status": true, "message": "Team Creation Success", "data": {} } ``` ### 6. Get Pending Invitations for a team Endpoint: **GET** `/api/v1/teams/:team_id/pending_invitations` Response Body: ```json { "status": true, "message": "Pending invitations for team retrieved", "data": [ { "invitation_id": 2, "team_id": "MLNT83MW9Q", "invitee_id": "MLNU0B6L4D", "invitee_email": "pranav@melinia.in", "invitee_first_name": "Pranav", "invitee_last_name": "DON DON", "inviter_id": "MLNUVS262W", "inviter_email": "vishal@gmail.com", "status": "pending" }, { "invitation_id": 1, "team_id": "MLNT83MW9Q", "invitee_id": "MLNUU2Z10H", "invitee_email": "kottesh@gmail.com", "invitee_first_name": "Shree", "invitee_last_name": "Kottes", "inviter_id": "MLNUVS262W", "inviter_email": "vishal@gmail.com", "status": "pending" } ] } ``` ### 7. Accept Invitation Endpoint: **POST** `/api/v1/teams/pending_invitations/:invitation_id` Response Body: ```jsonld { status: true, message: 'Invitation accepted successfully', data: { } } ``` ### 8. Reject Invitation Endpoint: **PUT** `/api/v1/teams/pending_invitations/:invitation_id` Response Body: ```jsonld { status: true, message: 'Invitation declined successfully', data: { } } ``` ### 9. Delete Invitations (by the leader) Endpoint: **PUT** `/api/v1/teams/:team_id/pending_invitations/:invitation_id` Response Body: ```jsonld { status: true, message: 'Invitation deleted successfully', data: { } } ``` ## User & Profile Management * Endpoint: `/api/v1` * pass the auth token for all these requests ### 1. Get User Profile Endpoint: **GET** `/api/v1/profile` Response Body: ```json { "details": { "firstName": "John", "lastName": "Doe", "college": "MIT", "degree": "B.Tech", "otherDegree": null, "year": 3 } } ``` or ```json { "details": { "firstName": "John", "lastName": "Doe", "college": "MIT", "degree": "other", "otherDegree": "some fancy custom degree", "year": 3 } } ``` ### 2. Get Full User Information Endpoint: **GET** `/api/v1/me` Response Body: ```json { "details": { "firstName": "John", "lastName": "Doe", "email": "john@example.com", "ph_no": "9876543210", "id": "MLNU123ABC", "college": "MIT", "degree": "B.Tech", "otherDegree": null, "year": 3 } } ``` ### 3. Create Profile Endpoint: **POST** `/api/v1/profile` Request Body: ```json { "firstName": "John", "lastName": "Doe", "college": "MIT", "degree": "B.Tech", "otherDegree": null, "year": 3, "ph_no": "9876543210" } ``` or ```json { "firstName": "John", "lastName": "Doe", "college": "MIT", "degree": "other", "otherDegree": "some fancy degree", "year": 3, "ph_no": "9876543210" } ``` **Constraints:** - `firstName`: 1-80 characters - `lastName`: 1-80 characters (optional) - `ph_no`: Exactly 10 digits - `year`: 1-5 - If `degree` is "other", `otherDegree` must be provided and non-empty - If `degree` is not "other", `otherDegree` must be null or undefined Response Body: ```json { "status": true, "message": "Profile created successfully" } ``` ### 4. Update Profile Endpoint: **PUT** `/api/v1/profile` Request Body: ```json { "firstName": "Jane", "lastName": "Smith", "college": "Stanford", "degree": "M.Tech", "otherDegree": null, "year": 2, "ph_no": "9876543210" } ``` **Constraints:** Same as Create Profile Response Body: ```json { "status": true, "message": "Profile updated successfully" } ``` ### 5. Get Pending Invitations for User Endpoint: **GET** `/api/v1/pending_invitations` Response Body: ```json { "invitations": [ { "invitation_id": 2, "team_id": "MLNT83MW9Q", "invitee_id": "MLNU0B6L4D", "invitee_email": "pranav@melinia.in", "invitee_first_name": "Pranav", "invitee_last_name": "DON DON", "inviter_id": "MLNUVS262W", "inviter_email": "vishal@gmail.com", "status": "pending" } ] } ``` --- # PAYMENTS Endpoint: GET /api/v1/payment/payment-status Authentication: Required ## Authentication - *Type*: Bearer Token (JWT) - *Header*: `Authorization: Bearer <your-auth-token>` - *Middleware*: Uses `authMiddleware` to validate JWT token - *Extracted*: User ID from token (`user_id`) ## Request Parameters *Headers:* - `Authorization` (required): Bearer token string ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` *Query Parameters:* None *Request Body:* None required ## Response Details ### Success Response - Payment Paid *Status Code:* `200 OK` *Headers:* - `Content-Type`: `application/json` *Response Body:* ```json { "paid": true } ``` *Description:* User has successfully completed payment for Melinia registration --- ### Response - Payment Pending *Status Code:* `202 Accepted` *Headers:* - `Content-Type`: `application/json` *Response Body:* ```json { "error": "Payment pending" } ``` *Description:* Payment order has been created but payment is not yet completed. User needs to complete the payment via Razorpay. --- ### Response - Payment Failed *Status Code:* `402 Payment Required` *Headers:* - `Content-Type`: `application/json` *Response Body:* ```json { "error": "Payment failed" } ``` *Description:* Payment attempt was unsuccessful. User should retry payment. --- ### Response - Payment Refunded *Status Code:* `402 Payment Required` *Headers:* - `Content-Type`: `application/json` *Response Body:* ```json { "error": "Payment refunded" } ``` *Description:* Payment was refunded by the system. --- ### Response - No Payment Record *Status Code:* `404 Not Found` *Headers:* - `Content-Type`: `application/json` *Response Body:* ```json { "error": "No payment record found" } ``` *Description:* User has not initiated any payment yet. User needs to create a payment order via `POST /api/v1/payment/register-melinia`. --- ### Response - User Not Found *Status Code:* `404 Not Found` *Headers:* - `Content-Type`: `application/json` *Response Body:* ```json { "error": "User not found" } ``` *Description:* The authenticated user ID does not exist in the database. --- ### Response - Invalid Payment State *Status Code:* `500 Internal Server Error` *Headers:* - `Content-Type`: `application/json` *Response Body:* ```json { "error": "Invalid payment state" } ``` *Description:* Payment status is in an unrecognized state (not PAID, CREATED, FAILED, or REFUNDED). --- ### Response - Internal Server Error *Status Code:* `500 Internal Server Error` *Headers:* - `Content-Type`: `application/json` *Response Body:* ```json { "error": "Internal server error" } ``` *Description:* Server encountered an unexpected error while checking payment status. ## Event Management ### 1. Create Event: - api/v1/events/ Endpoint: POST `http://localhost:3000/api/v1/events` Req Body: ```json { "name": "Hackathon 2026", "description": "A flagship technical hackathon to solve real-world sustainability challenges.", "participationType": "team", "eventType": "technical", "maxAllowed": 50, "minTeamSize": 3, "maxTeamSize": 5, "venue": "Main Auditorium & Lab Block", "startTime": "2026-05-01T09:00:00Z", "endTime": "2026-05-02T18:00:00Z", "registrationStart": "2026-04-01T00:00:00Z", "registrationEnd": "2026-04-30T23:59:59Z", "rounds": [ { "roundNo": 1, "roundName": "Prelims", "roundDescription": "Idea Screening and Abstract Submission", "startTime": "2026-05-01T09:00:00Z", "endTime": "2026-05-01T12:00:00Z" }, { "roundNo": 2, "roundName": "Finals", "roundDescription": "24-Hour Hack and Final Pitch", "startTime": "2026-05-01T13:00:00Z", "endTime": "2026-05-02T18:00:00Z" } ], "prizes": [ { "position": 1, "rewardValue": 50000 }, { "position": 2, "rewardValue": 30000 } ], "rules": [ { "roundNo": null, "ruleNumber": 1, "ruleDescription": "All participants must carry their university ID cards." }, { "roundNo": 1, "ruleNumber": 1, "ruleDescription": "Abstracts must not exceed 500 words and should be in PDF format." }, { "roundNo": 2, "ruleNumber": 1, "ruleDescription": "Use of pre-built templates is allowed, but the core logic must be written during the event." } ], "organizers": ["71762231036@cit.edu.in"] } ``` Response Body: ```json { "status": true, "message": "Event details retrieved successfully", "data": {} } ``` ### 2. Get all Events: - api/v1/events Endpoint: GET `http://localhost:3000/api/v1/events` Req Body: ```json No Parameters required ``` Response Body: ```json { "status": true, "message": "Events fetched successfully", "data": {} } ``` ### 3. Get Event by id: - api/events/:id Endpoint: GET `http://localhost:3000/api/v1/events/:id` Req Body: ```json No parameters required ``` Response Body: ```json { "status": true, "message": "Event details retrieved successfully", "data": {} } ``` ### 4. Update Event by id: - api/events/:id Endpoint: PATCH `http://localhost:3000/api/v1/events/:id` Req Body: ```json { "name": "Startup Pitch 2026", "description": "Business idea pitching competition", "participationType": "team", "eventType": "non-technical", "maxAllowed": 15, "minTeamSize": 5, "maxTeamSize": 5, "venue": "Shark Tank Stage", "startTime": "2026-05-01T14:00:00Z", "endTime": "2026-05-01T19:00:00Z", "registrationStart": "2026-04-15T00:00:00Z", "registrationEnd": "2026-04-30T23:59:59Z", "createdBy": "MLNUNC2T52", "rounds": [ {"roundNo": 1, "roundName":"optional", "roundDescription": "Pitch round"}, {"roundNo": 2, "roundName":"optional", "roundDescription": "Q&A round"} ], "prizes": [ {"position": 1, "rewardValue": 100000}, {"position": 2, "rewardValue": 50000}, {"position": 3, "rewardValue": 25000} ] } ``` Response Body: ```json { "status": true, "message": "Event updated successfully", "data": {} } ``` ### 5. Delete Event by id: - api/events/:id Endpoint: DELETE `http://localhost:3000/api/v1/events/:id` Req Body: ```json No parameters required ``` Response Body: ```json { "status": true, "message": "Event deleted successfully", "data": {} } ``` ### 6. Register for an Event (with event id): - /events/:id/register Endpoint: POST `http://localhost:3000/api/v1/events/:id/register` Req Body: ```json { "teamId": "MLNT67WW5M" } ``` Response Body: ```json { "status": true, "message": "Event registration successful", "data": { "id": 4, "event_id": "MLNE20A4EF", "team_id": "MLNT67WW5M", "user_id": "MLNUVS262W", "registered_at": "2025-12-29T14:00:01.118Z" } } ```

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.