# Tuitional AI API Documentation This document outlines the API endpoints required by the Tuitional AI frontend application. ## Base URL All API endpoints should be accessible from a base URL: `https://api.tuitional.ai/v1` or your own domain. ## Authentication ### Authentication Headers All authenticated endpoints require an Authorization header: ``` Authorization: Bearer ``` ### Authentication Endpoints #### Register User - **URL**: `/auth/register` - **Method**: `POST` - **Description**: Creates a new user account - **Request Body**: ```json { "email": "user@example.com", "password": "securePassword123", "fullName": "John Doe", "role": "student" // or "teacher" or "admin" } ``` - **Response**: ```json { "token": "jwt_token_here", "user": { "id": "user_id", "email": "user@example.com", "role": "student", "profileCompleted": false, "fullName": "John Doe" } } ``` #### Login User - **URL**: `/auth/login` - **Method**: `POST` - **Description**: Authenticates a user and returns a token - **Request Body**: ```json { "email": "user@example.com", "password": "securePassword123" } ``` - **Response**: ```json { "token": "jwt_token_here", "user": { "id": "user_id", "email": "user@example.com", "role": "student", "profileCompleted": true, "fullName": "John Doe" } } ``` #### Verify Token - **URL**: `/auth/verify` - **Method**: `POST` - **Description**: Verifies if a token is valid - **Request Body**: ```json { "token": "jwt_token_here" } ``` - **Response**: ```json { "valid": true, "user": { "id": "user_id", "email": "user@example.com", "role": "student", "profileCompleted": true, "fullName": "John Doe" } } ``` ## User Profiles ### Student Profiles #### Create/Update Student Profile - **URL**: `/profile/student` - **Method**: `POST` - **Description**: Creates or updates a student profile - **Authentication**: Required - **Request Body**: ```json { "fullName": "John Doe", "phoneNumber": "123-456-7890", "grade": "Grade 10", "curriculum": "CAIE", "level": "Intermediate", "country": "United States", "school": "International School" } ``` - **Response**: ```json { "userId": "user_id", "fullName": "John Doe", "phoneNumber": "123-456-7890", "grade": "Grade 10", "curriculum": "CAIE", "level": "Intermediate", "country": "United States", "school": "International School" } ``` #### Get Student Profile - **URL**: `/profile/student/:userId` - **Method**: `GET` - **Description**: Retrieves a student's profile - **Authentication**: Required - **Response**: ```json { "userId": "user_id", "fullName": "John Doe", "phoneNumber": "123-456-7890", "grade": "Grade 10", "curriculum": "CAIE", "level": "Intermediate", "country": "United States", "school": "International School" } ``` ### Teacher Profiles #### Create/Update Teacher Profile - **URL**: `/profile/teacher` - **Method**: `POST` - **Description**: Creates or updates a teacher profile - **Authentication**: Required - **Request Body**: ```json { "fullName": "Jane Smith", "phoneNumber": "987-654-3210", "grade": "Multiple", "curriculum": "CAIE", "level": "Advanced", "country": "United Kingdom", "school": "Cambridge Academy", "position": "Science Teacher" } ``` - **Response**: ```json { "userId": "user_id", "fullName": "Jane Smith", "phoneNumber": "987-654-3210", "grade": "Multiple", "curriculum": "CAIE", "level": "Advanced", "country": "United Kingdom", "school": "Cambridge Academy", "position": "Science Teacher" } ``` #### Get Teacher Profile - **URL**: `/profile/teacher/:userId` - **Method**: `GET` - **Description**: Retrieves a teacher's profile - **Authentication**: Required - **Response**: ```json { "userId": "user_id", "fullName": "Jane Smith", "phoneNumber": "987-654-3210", "grade": "Multiple", "curriculum": "CAIE", "level": "Advanced", "country": "United Kingdom", "school": "Cambridge Academy", "position": "Science Teacher" } ``` ## MindPages ### Get MindPages - **URL**: `/mindpage/user/:userId` - **Method**: `GET` - **Description**: Retrieves all mind pages for a specific user - **Authentication**: Required - **Response**: ```json [ { "id": "page_id_1", "user_id": "user_id", "title": "Chemistry Notes", "content": "

These are my chemistry notes.

", "tags": ["chemistry", "notes"], "folder_path": "root", "page_type": "note", "is_starred": false, "shared_with": [], "created_at": "2023-04-15T10:00:00Z", "updated_at": "2023-04-15T10:30:00Z" }, { "id": "page_id_2", "user_id": "user_id", "title": "Physics Formulas", "content": "

Key physics formulas.

", "tags": ["physics", "formulas"], "folder_path": "root", "page_type": "note", "is_starred": true, "shared_with": [], "created_at": "2023-04-16T10:00:00Z", "updated_at": "2023-04-16T10:30:00Z" } ] ``` ### Get Single MindPage - **URL**: `/mindpage/:id` - **Method**: `GET` - **Description**: Retrieves a specific mind page by ID - **Authentication**: Required - **Response**: ```json { "id": "page_id", "user_id": "user_id", "title": "Chemistry Notes", "content": "

These are my chemistry notes.

", "tags": ["chemistry", "notes"], "folder_path": "root", "page_type": "note", "is_starred": false, "shared_with": [], "created_at": "2023-04-15T10:00:00Z", "updated_at": "2023-04-15T10:30:00Z" } ``` ### Create MindPage - **URL**: `/mindpage` - **Method**: `POST` - **Description**: Creates a new mind page - **Authentication**: Required - **Request Body**: ```json { "userId": "user_id", "title": "New Study Notes", "content": "

This is the content of my notes.

", "tags": ["study", "notes"], "folder_path": "root", "page_type": "note" } ``` - **Response**: ```json { "id": "new_page_id", "user_id": "user_id", "title": "New Study Notes", "content": "

This is the content of my notes.

", "tags": ["study", "notes"], "folder_path": "root", "page_type": "note", "is_starred": false, "shared_with": [], "created_at": "2023-04-20T15:00:00Z", "updated_at": "2023-04-20T15:00:00Z" } ``` ### Update MindPage - **URL**: `/mindpage/:id` - **Method**: `PUT` - **Description**: Updates an existing mind page - **Authentication**: Required - **Request Body**: ```json { "title": "Updated Study Notes", "content": "

This is the updated content.

", "tags": ["study", "notes", "updated"], "is_starred": true } ``` - **Response**: ```json { "id": "page_id", "user_id": "user_id", "title": "Updated Study Notes", "content": "

This is the updated content.

", "tags": ["study", "notes", "updated"], "folder_path": "root", "page_type": "note", "is_starred": true, "shared_with": [], "created_at": "2023-04-20T15:00:00Z", "updated_at": "2023-04-20T15:30:00Z" } ``` ### Delete MindPage - **URL**: `/mindpage/:id` - **Method**: `DELETE` - **Description**: Deletes a mind page - **Authentication**: Required - **Response**: ```json { "success": true, "message": "Mind page deleted successfully" } ``` ### Share MindPage - **URL**: `/mindpage/:id/share` - **Method**: `PUT` - **Description**: Shares a mind page with other users - **Authentication**: Required - **Request Body**: ```json { "sharedWith": ["user_id_1", "user_id_2"] } ``` - **Response**: ```json { "success": true, "message": "Mind page shared successfully" } ``` ## Groups ### Get User Groups - **URL**: `/groups/user/:userId` - **Method**: `GET` - **Description**: Retrieves all groups a user belongs to - **Authentication**: Required - **Response**: ```json [ { "id": "group_id_1", "name": "Physics Study Group", "description": "A group for studying physics", "owner_id": "owner_user_id", "created_at": "2023-04-10T12:00:00Z", "members": [ { "user_id": "user_id", "role": "member", "joined_at": "2023-04-11T10:00:00Z" } ] } ] ``` ### Create Group - **URL**: `/groups` - **Method**: `POST` - **Description**: Creates a new group - **Authentication**: Required - **Request Body**: ```json { "name": "Chemistry Study Group", "description": "A group for studying chemistry", "owner_id": "user_id" } ``` - **Response**: ```json { "id": "new_group_id", "name": "Chemistry Study Group", "description": "A group for studying chemistry", "owner_id": "user_id", "created_at": "2023-04-20T15:00:00Z", "members": [ { "user_id": "user_id", "role": "owner", "joined_at": "2023-04-20T15:00:00Z" } ] } ``` ### Invite to Group - **URL**: `/groups/:groupId/invite` - **Method**: `POST` - **Description**: Invites a user to a group - **Authentication**: Required - **Request Body**: ```json { "email": "invited_user@example.com", "invited_by": "user_id" } ``` - **Response**: ```json { "success": true, "message": "Invitation sent successfully", "invitation_id": "invitation_id" } ``` ### Accept Invitation - **URL**: `/groups/invitations/:invitationId/accept` - **Method**: `POST` - **Description**: Accepts a group invitation - **Authentication**: Required - **Request Body**: ```json { "userId": "invited_user_id" } ``` - **Response**: ```json { "success": true, "message": "You've been added to the group", "group_id": "group_id" } ``` ## Error Handling All API endpoints should return appropriate HTTP status codes: - `200 OK`: The request was successful - `201 Created`: A resource was successfully created - `400 Bad Request`: The request was invalid - `401 Unauthorized`: Authentication is required - `403 Forbidden`: The user does not have permission - `404 Not Found`: The requested resource was not found - `500 Internal Server Error`: An error occurred on the server Error responses should have this structure: ```json { "error": { "code": "ERROR_CODE", "message": "Human-readable error message" } } ``` ## Implementation Notes 1. **Security**: Implement proper validation for all inputs 2. **Rate Limiting**: Consider implementing rate limiting to prevent abuse 3. **CORS**: Configure CORS to allow requests from the frontend domain 4. **Pagination**: For endpoints that return lists, consider implementing pagination 5. **Caching**: Implement appropriate caching strategies for read-heavy endpoints 6. **Logging**: Log API requests for debugging and monitoring purposes 7. **Documentation**: Keep this documentation updated as the API evolves This documentation provides a basic structure for the backend API. Extend it as needed to support additional features of the Tuitional AI application.