📘 ITCPR API Documentation

Welcome to the official ITCPR API documentation. This API powers various internal and external services including LaTeX document generation, GitHub integration, Discord automation, ZeroTier management, email utilities, WSL command syncing, and server operations.

🔗 Base URL

All endpoints are available under:

https://api.itcpr.org

All requests and responses are in JSON format unless otherwise noted.

🚀 Quickstart

All endpoints support CORS.
Authentication is handled via service-specific tokens (if applicable).
Rate limiting may apply on high-frequency endpoints.

📂 Endpoints

📄 LaTeX Services

`POST /latex/compile`

Description:
Compile LaTeX documents, including support for BibTeX and embedded figures (as base64).

Payload:

{
  "content": "<LaTeX code>",
  "bibliography": "<optional .bib content>",
  "figures": [
    {
      "name": "fig1.png",
      "data": "data:image/png;base64,..."
    }
  ],
  "debug": false
}

Response: Returns a compiled PDF document as binary. If debug: true, logs are included in X-Log-Preview header.

💬 Discord Bot Integration

`POST /discord/message`

Send a plain text message to a specific Discord channel. Optionally reply to a message.

{
  "channelId": "DISCORD_CHANNEL_ID",
  "message": "Hello from ITCPR API",
  "replyToMessageId": "OPTIONAL_MESSAGE_ID"
}

Response: Returns message ID on success.

`POST /discord/add_user`

Add a user to the guild (server) using OAuth2 access_token.

{
  "userId": "DISCORD_USER_ID",
  "accessToken": "OAUTH_ACCESS_TOKEN"
}

`POST /discord/remove_user`

Remove a user from the guild.

{
  "userId": "DISCORD_USER_ID"
}

`POST /discord/assign_role`

Assign an existing role to a user within a guild.

{
  "userId": "DISCORD_USER_ID",
  "roleId": "DISCORD_ROLE_ID"
}

`POST /discord/user_msg`

Send a direct message to a Discord user.

{
  "userId": "DISCORD_USER_ID",
  "message": "Your message here"
}

📧 Email Delivery

`POST /email/unigurubd`

Send emails via UniGuruBD SMTP credentials.

`POST /email/itcpr`

Send emails via ITCPR's dedicated SMTP gateway.

Shared Payload:

{
  "to": "recipient@example.com",
  "subject": "Hello from ITCPR",
  "message": "<p>This is an HTML or plain text email body</p>"
}

`POST /email/send`

Send emails via ITCPR SMTP with sender tracking. Emails to @mail.itcpr.org are stored in Firebase inbox.

{
  "to": "recipient@example.com",
  "from": "sender@example.com",
  "subject": "Hello from ITCPR",
  "message": "<p>Email body</p>"
}

`POST /email/incoming`

Receive incoming emails (webhook endpoint for email service).

`POST /email/chessbd`

Send emails via ChessBD SMTP credentials.

{
  "to": "recipient@example.com",
  "from": "sender@example.com",
  "subject": "Subject",
  "message": "Email body"
}

👥 Portal & Application Management

`GET /apply/all`

Get all applications (staff only). Requires Firebase ID token in Authorization: Bearer <token> header.

`POST /portal/newuser`

Create a new user in Firebase Auth (staff only). Requires Firebase ID token.

{
  "email": "newuser@example.com"
}

`POST /portal/remove_user`

Remove a user from Firebase Auth and Firestore (staff only). Requires Firebase ID token.

{
  "uid": "USER_UID"
}

🌐 ZeroTier Network Access

`POST /zerotier/authenticate`

Authorize a device in the ZeroTier network and assign a static IP.

{
  "member_id": "ZT_MEMBER_ID",
  "ip": "192.168.195.10",
  "name": "Device Name"
}

`POST /zerotier/deauthenticate`

Remove a member from the ZeroTier network.

{
  "member_id": "ZT_MEMBER_ID"
}

📁 GitHub File Services

`GET /github/get_files?path=...`

List files in a specified GitHub repository path. Path must include 'files'.

`GET /github/apply/get_files?path=...`

List files in the apply repository path. Path must include 'files'.

`POST /github/upload_file?path=...`

Upload a file to a GitHub repository.

Form Data:
- file: file input
- path: destination folder under /files/

`POST /github/apply/upload?path=...`

Upload a file to the apply GitHub repository.

Form Data:
- file: file input
- path: destination folder under /files/

`POST /github/webhook`

Trigger a Discord message when someone pushes to the repo.

☁️ Cloud Storage Services

`POST /cloudflare/upload`

Upload a file to Cloudflare R2 storage.

Form Data: - file: file input

Response: Returns unique path and public URL.

`POST /supabase/upload_file`

Upload a file to Supabase storage.

Form Data: - file: file input

Response: Returns unique path and public URL.

🐧 WSL Command Sync

`POST /wsl/upload`

Upload a .txt file to WSL for logging or syncing purposes.

Form Data: - file: .txt file

`GET /wsl/download`

Download the current log file stored on WSL.

`POST /wsl/session`

Upload a .json session file to WSL.

Form Data: - file: .json file

📊 Server Operations

`POST /server/webhook`

Update internal server metrics via a JSON POST.

{
  "file": "server_stats.json",
  "data": {
    "cpu": 45.2,
    "memory": 60.1
  }
}

`POST /server/stats`

Retrieve latest saved system stats.

{
  "file": "server_stats.json"
}

`POST /server/access`

Upload access_codes.json to the server.

Form Data: - file: .json file

`POST /server/download`

Download a specific file from the server.

{
  "filename": "access_codes.json"
}

`POST /server/job_upload`

Upload a job output zip file with metadata.

Form Data: - file: .zip file - metadata: JSON file with user_id and job_id

`POST /server/job_download`

Download a job output zip file.

{
  "user_id": "user123",
  "job_id": "job456"
}

`POST /server/job_delete`

Delete a job output directory.

{
  "user_id": "user123",
  "job_id": "job456"
}

`POST /server/wake`

Send Wake-on-LAN command to a PC and log the request.

{
  "username": "user@example.com"
}

📚 Library Services

`GET /library/fetch`

Fetch all books from the library database.

`POST /library/add`

Add a new book to the library.

{
  "title": "Book Title",
  "author": "Author Name",
  "publisher": "Publisher",
  "publication_date": "2024-01-01",
  "edition": "1st",
  "pdf_name": "book.pdf"
}

`POST /library/edit`

Edit an existing book.

{
  "id": "bk000001",
  "title": "Updated Title",
  "author": "Updated Author"
}

`DELETE /library/delete`

Delete a book from the library.

{
  "id": "bk000001"
}

`POST /library/upload?request_id=...`

Upload a PDF file for a book (temporary storage).

Form Data: - file: PDF file

`GET /library/pdf?request_id=...`

Download a PDF file by request ID. File is deleted after download.

🤖 AI Services

`POST /gemini/ask`

Query Google Gemini AI model.

{
  "message": "What is the capital of France?"
}

Response:

{
  "response": "The capital of France is Paris."
}

🔐 Authentication

`POST /auth/sso`

Single Sign-On authentication using Firebase ID token.

{
  "email": "user@example.com",
  "password": "password",
  "firebaseIdToken": "FIREBASE_ID_TOKEN"
}

Response:

{
  "success": true,
  "customToken": "FIREBASE_CUSTOM_TOKEN"
}

🛠️ Tools

`GET /tool/itcpr_calendar_ics`

Get ITCPR calendar in iCal format. Returns text/calendar content.

☁️ Cloud ITCPR / GitHub App Management

`POST /cloud/github/webhook`

Handle GitHub App webhook events (installation, repository, member, etc.).

`POST /cloud/app/oauth/url`

Generate OAuth URL for GitHub App authentication.

{
  "redirect_uri": "https://cloud.itcpr.org/github/callback"
}

Response:

{
  "url": "https://github.com/login/oauth/authorize?...",
  "state": "STATE_TOKEN"
}

`POST /cloud/app/oauth/callback`

Handle OAuth callback and exchange code for token.

{
  "code": "AUTHORIZATION_CODE",
  "state": "STATE_TOKEN"
}

`GET /cloud/app/connection`

Check if user has connected GitHub account. Requires X-User-ID header.

`POST /cloud/app/disconnect`

Disconnect user's GitHub account. Requires X-User-ID header.

`GET /cloud/app/user`

Get authenticated user's GitHub information. Requires X-User-ID header.

`GET /cloud/app/org`

Get organization information and statistics.

`GET /cloud/app/org/members`

Get all organization members.

`GET /cloud/app/org/membership`

Check if authenticated user is a member of the organization.

`POST /cloud/app/org/invite`

Invite a user to the organization by username.

{
  "username": "github_username"
}

`DELETE /cloud/app/org/members/<username>`

Remove a member from the organization.

`GET /cloud/app/org/teams`

Get all teams in the organization.

`GET /cloud/app/org/teams/<team_slug>/members`

Get team members.

`PUT /cloud/app/org/teams/<team_slug>/members`

Add user to team.

{
  "username": "github_username",
  "role": "member"
}

`DELETE /cloud/app/org/teams/<team_slug>/members/<username>`

Remove user from team.

`POST /cloud/app/org/teams`

Create a new team.

{
  "name": "Team Name",
  "description": "Team description",
  "privacy": "closed"
}

`PATCH /cloud/app/org/teams/<team_slug>`

Update team information.

`DELETE /cloud/app/org/teams/<team_slug>`

Delete a team.

`GET /cloud/app/org/repos`

Get all organization repositories (public and private).

`POST /cloud/app/org/repos`

Create a new repository in the organization.

{
  "name": "repo-name",
  "description": "Repository description",
  "visibility": "private",
  "template": "project-template"
}

`GET /cloud/app/repos/<owner>/<repo>`

Get repository details.

`DELETE /cloud/app/repos/<owner>/<repo>`

Delete a repository.

`GET /cloud/app/repos/<owner>/<repo>/collaborators`

Get repository collaborators.

`PUT /cloud/app/repos/<owner>/<repo>/collaborators/<username>`

Add or update a collaborator.

{
  "permission": "push"
}

`DELETE /cloud/app/repos/<owner>/<repo>/collaborators/<username>`

Remove a collaborator.

`PATCH /cloud/app/repos/<owner>/<repo>/collaborators/<username>`

Update a collaborator's permission.

{
  "permission": "admin"
}

`PUT /cloud/app/repos/<owner>/<repo>/teams/<team_slug>`

Add team to repository.

{
  "permission": "push"
}

`DELETE /cloud/app/repos/<owner>/<repo>/teams/<team_slug>`

Remove team from repository.

🔌 Device Authentication API (for CLI tools)

`POST /api/device/start`

Start device authentication flow - generate device code.

Response:

{
  "device_code": "ABC12345",
  "user_code": "ABCD-1234",
  "verification_uri": "https://api.itcpr.org/device?code=ABCD-1234",
  "expires_in": 600,
  "interval": 5
}

`GET /api/device/poll?device_code=...`

Poll for device authentication approval.

Response (pending):

{
  "status": "pending"
}

Response (approved):

{
  "device_id": "uuid",
  "device_token": "token_string"
}

`POST /api/device/approve`

Approve device authentication (called from frontend). Requires authentication.

{
  "device_code": "ABCD-1234",
  "device_name": "My CLI Device"
}

`POST /api/device/deny`

Deny device authentication (called from frontend).

{
  "device_code": "ABCD-1234"
}

`POST /api/device/revoke`

Revoke a device token.

{
  "device_id": "device_uuid"
}

`GET /api/agent/devices`

Get all devices for current user. Requires X-User-ID header.

`GET /api/agent/me`

Get current device/user information. Requires Authorization: Bearer <device_token> header.

`GET /api/agent/repos`

Get repositories assigned to this device/user. Requires Authorization: Bearer <device_token> header.

`POST /api/agent/token`

Get short-lived GitHub installation token for repository access. Requires Authorization: Bearer <device_token> header.

{
  "repo": "optional-repo-name"
}

📦 Headers & Content-Type

All endpoints (unless file upload) expect:

Content-Type: application/json

Use appropriate headers for file uploads via multipart/form-data.

🧪 Example Request (cURL)

curl -X POST https://api.itcpr.org/email/itcpr \
  -H "Content-Type: application/json" \
  -d '{
    "to": "you@example.com",
    "subject": "Welcome!",
    "message": "Hello from ITCPR API."
  }'

🧑‍💻 Developer Notes

All errors return an appropriate HTTP status code and JSON body with "error" and "details" fields.
PDF responses from /latex/compile include Content-Type: application/pdf.
Some endpoints like ZeroTier and GitHub require credentials configured via environment variables on the server.
Use reverse proxies (e.g. nginx) with SSL termination in production deployments.