Skip to content

API Reference

Complete reference for HKFR's REST API endpoints.

Authentication

All API endpoints (except public ones) require JWT authentication via HTTP-only cookies.

Authentication Flow

sequenceDiagram
    participant C as Client
    participant A as API
    participant DB as Database

    C->>A: POST /api/auth/login
    A->>DB: Validate credentials
    A->>C: Set-Cookie: token, refresh_token

    Note over C,A: Authenticated requests
    C->>A: API request with cookies
    A->>A: Verify JWT token
    A->>C: Response

Base URL

Production: https://hkfr.live/api
Development: http://localhost:3000/api

Authentication Endpoints

POST /api/auth/register

Register a new user account.

Request Body: 

{
  "email": "user@example.com",
  "password": "securepassword123",
  "confirmPassword": "securepassword123",
  "name": "John Doe",
  "company": "Acme Corp"
}

Response: 

{
  "message": "User registered successfully",
  "userId": "64a7b8c9d1e2f3a4b5c6d7e8"
}

Status Codes: - 201: User created successfully - 400: Invalid input or password mismatch - 409: User already exists

POST /api/auth/login

Authenticate user and return JWT tokens.

Request Body: 

{
  "email": "user@example.com",
  "password": "securepassword123",
  "isVisitor": false
}

Response: 

{
  "message": "Login successful",
  "user": {
    "id": "64a7b8c9d1e2f3a4b5c6d7e8",
    "email": "user@example.com",
    "role": "USER"
  }
}

Headers Set: - Set-Cookie: token=<jwt_access_token>; HttpOnly; Path=/ - Set-Cookie: refresh_token=<jwt_refresh_token>; HttpOnly; Path=/

Status Codes: - 200: Login successful - 401: Invalid credentials - 400: Missing required fields

POST /api/auth/refresh

Refresh expired access token using refresh token.

Request: Requires refresh_token cookie

Response: 

{
  "message": "Token refreshed successfully"
}

Headers Set: - Set-Cookie: token=<new_jwt_access_token>; HttpOnly; Path=/

Status Codes: - 200: Token refreshed successfully - 401: Invalid refresh token - 403: Refresh token expired

POST /api/auth/logout

Logout user and clear authentication cookies.

Response: 

{
  "message": "Logged out successfully"
}

Headers Set: - Set-Cookie: token=; HttpOnly; Path=/; Max-Age=0 - Set-Cookie: refresh_token=; HttpOnly; Path=/; Max-Age=0

Status Codes: - 200: Logout successful

POST /api/auth/verify

Verify email address using verification token.

Request Body: 

{
  "token": "email_verification_token"
}

Response: 

{
  "message": "Email verified successfully"
}

Status Codes: - 200: Email verified successfully - 400: Invalid or expired token

Document Management Endpoints

GET /api/manage_files/get_documents

Retrieve all documents accessible to the authenticated user.

Authentication: Required

Response: 

{
  "documents": [
    {
      "_id": "64a7b8c9d1e2f3a4b5c6d7e8",
      "filename": "Annual Report 2024",
      "fileType": "report",
      "fileSize": 1024000,
      "uploader": "64a7b8c9d1e2f3a4b5c6d7e8",
      "access": ["64a7b8c9d1e2f3a4b5c6d7e8"],
      "createdAt": "2024-01-15T10:30:00Z",
      "changedAt": "2024-01-20T14:45:00Z"
    }
  ]
}

Status Codes: - 200: Documents retrieved successfully - 401: Unauthorized - 403: Invalid token

POST /api/manage_files/create

Create a new document.

Authentication: Required (USER role)

Request Body: 

{
  "filename": "Q4 Financial Report",
  "fileType": "report"
}

Response: 

{
  "message": "Document created successfully",
  "documentId": "64a7b8c9d1e2f3a4b5c6d7e8",
  "gcsPath": "user_id/document_id.md"
}

Status Codes: - 201: Document created successfully - 400: Missing required fields - 409: Document with same name already exists - 403: Access denied

GET /api/manage_files/get_document_content

Retrieve document content from Google Cloud Storage.

Authentication: Required

Query Parameters: - documentId: MongoDB ObjectId of the document

Response: 

{
  "content": "# Document Title\n\nDocument content in markdown format...",
  "metadata": {
    "filename": "Annual Report 2024",
    "fileType": "report",
    "lastModified": "2024-01-20T14:45:00Z"
  }
}

Status Codes: - 200: Content retrieved successfully - 400: Missing documentId - 403: Access denied to document - 404: Document not found

POST /api/manage_files/save

Save document content to Google Cloud Storage.

Authentication: Required

Request Body: 

{
  "documentId": "64a7b8c9d1e2f3a4b5c6d7e8",
  "content": "# Updated Document\n\nNew content here..."
}

Response: 

{
  "message": "Document saved successfully",
  "savedAt": "2024-01-20T15:30:00Z"
}

Status Codes: - 200: Document saved successfully - 400: Missing required fields - 403: Access denied to document - 404: Document not found

POST /api/manage_files/upload

Upload files (Excel, images, etc.) to be processed and integrated.

Authentication: Required

Request: multipart/form-data - file: File to upload - documentId: Target document ID (optional)

Response: 

{
  "message": "File uploaded successfully",
  "fileId": "64a7b8c9d1e2f3a4b5c6d7e8",
  "processingStatus": "queued",
  "gcsPath": "uploads/user_id/file_id.xlsx"
}

Status Codes: - 201: File uploaded successfully - 400: Invalid file or missing file - 413: File too large - 415: Unsupported file type

GET /api/manage_files/download

Download processed document or file.

Authentication: Required

Query Parameters: - documentId: Document to download - format: pdf or docx (default: pdf)

Response: Binary file content

Headers: - Content-Type: application/pdf or application/vnd.openxmlformats-officedocument.wordprocessingml.document - Content-Disposition: attachment; filename="document.pdf"

Status Codes: - 200: File downloaded successfully - 400: Invalid parameters - 403: Access denied - 404: File not found

POST /api/manage_files/export

Generate and export document in specified format.

Authentication: Required

Request Body: 

{
  "documentId": "64a7b8c9d1e2f3a4b5c6d7e8",
  "format": "pdf",
  "options": {
    "includeComments": false,
    "template": "professional"
  }
}

Response: 

{
  "exportId": "64a7b8c9d1e2f3a4b5c6d7e8",
  "downloadUrl": "/api/manage_files/download?exportId=64a7b8c9d1e2f3a4b5c6d7e8",
  "expiresAt": "2024-01-21T15:30:00Z"
}

Status Codes: - 201: Export job created successfully - 400: Invalid export parameters - 403: Access denied

DELETE /api/manage_files/delete

Delete a document permanently.

Authentication: Required (document owner only)

Request Body: 

{
  "documentId": "64a7b8c9d1e2f3a4b5c6d7e8"
}

Response: 

{
  "message": "Document deleted successfully"
}

Status Codes: - 200: Document deleted successfully - 400: Missing documentId - 403: Access denied (not owner) - 404: Document not found

POST /api/manage_files/rename

Rename an existing document.

Authentication: Required

Request Body: 

{
  "documentId": "64a7b8c9d1e2f3a4b5c6d7e8",
  "newName": "Updated Annual Report 2024"
}

Response: 

{
  "message": "Document renamed successfully",
  "newName": "Updated Annual Report 2024"
}

Status Codes: - 200: Document renamed successfully - 400: Missing required fields - 403: Access denied - 409: Name already exists

Collaboration Endpoints

POST /api/manage_files/add_collaborator

Add a collaborator to a document.

Authentication: Required (document owner or editor)

Request Body: 

{
  "documentId": "64a7b8c9d1e2f3a4b5c6d7e8",
  "userEmail": "collaborator@example.com",
  "role": "editor",
  "permissions": ["read", "write", "comment"]
}

Response: 

{
  "message": "Collaborator added successfully",
  "collaboratorId": "64a7b8c9d1e2f3a4b5c6d7e9"
}

Status Codes: - 201: Collaborator added successfully - 400: Invalid user email or role - 403: Access denied - 404: User not found

DELETE /api/manage_files/delete_collaborator

Remove a collaborator from a document.

Authentication: Required (document owner only)

Request Body: 

{
  "documentId": "64a7b8c9d1e2f3a4b5c6d7e8",
  "collaboratorId": "64a7b8c9d1e2f3a4b5c6d7e9"
}

Response: 

{
  "message": "Collaborator removed successfully"
}

Status Codes: - 200: Collaborator removed successfully - 403: Access denied (not owner) - 404: Collaborator not found

AI Features Endpoints

POST /api/generate_data

Generate content using AI assistance.

Authentication: Required

Request Body: 

{
  "prompt": "Generate an executive summary for a financial report",
  "context": {
    "documentType": "annual_report",
    "company": "Acme Corp",
    "fiscalYear": "2024"
  },
  "options": {
    "length": "medium",
    "tone": "professional"
  }
}

Response: 

{
  "generatedContent": "## Executive Summary\n\nAcme Corp has achieved...",
  "usage": {
    "tokensUsed": 150,
    "model": "gpt-4"
  }
}

Status Codes: - 200: Content generated successfully - 400: Invalid prompt or parameters - 429: Rate limit exceeded - 503: AI service unavailable

Utility Endpoints

GET /api/healthz

Health check endpoint for monitoring.

Authentication: Not required

Response: 

{
  "status": "ok",
  "timestamp": "2024-01-20T15:30:00Z",
  "version": "1.0.0"
}

Status Codes: - 200: Service healthy - 503: Service unhealthy

Error Responses

All endpoints may return these common error responses:

400 Bad Request

{
  "error": "Invalid request parameters",
  "details": {
    "field": "email",
    "message": "Valid email address required"
  }
}

401 Unauthorized

{
  "error": "Authentication required"
}

403 Forbidden

{
  "error": "Access denied",
  "reason": "Insufficient permissions"
}

404 Not Found

{
  "error": "Resource not found"
}

429 Rate Limited

{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

500 Internal Server Error

{
  "error": "Internal server error",
  "requestId": "req_64a7b8c9d1e2f3a4"
}

Rate Limiting

API endpoints are rate limited to prevent abuse:

  • Authentication endpoints: 10 requests per minute per IP
  • Document operations: 100 requests per minute per user
  • File uploads: 20 uploads per hour per user
  • AI generation: 50 requests per hour per user

Rate limit headers are included in responses: 

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

SDKs and Libraries

JavaScript/TypeScript

// Example usage with fetch
const response = await fetch('/api/manage_files/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include', // Important for cookies
  body: JSON.stringify({
    filename: 'My Report',
    fileType: 'report'
  })
});

const data = await response.json();

cURL Examples

# Login
curl -X POST https://hkfr.live/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}' \
  -c cookies.txt

# Create document (using saved cookies)
curl -X POST https://hkfr.live/api/manage_files/create \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"filename":"Test Report","fileType":"report"}'