API Overview

CodeNotify provides a comprehensive RESTful API for managing competitive programming contest notifications across multiple platforms.

Base URL

Development: http://localhost:3000
Production: https://api.codenotify.dev

API Version

Current version: v1 (no version prefix in URL)

Authentication

Most endpoints require JWT authentication. Include the access token in the Authorization header:

Authorization: Bearer <your_access_token>

Token Types

• Access Token: Short-lived (15 minutes), used for API requests
• Refresh Token: Long-lived (7 days), used to obtain new access tokens

Request Format

Headers

Content-Type: application/json
Authorization: Bearer <access_token>

Body

All POST/PATCH requests accept JSON payloads:

{
  "field1": "value1",
  "field2": "value2"
}

Response Format

Success Response

{
  "id": "string",
  "field1": "value1",
  "field2": "value2",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

Paginated Response

{
  "data": [...],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "hasNext": true,
    "hasPrev": false
  }
}

Error Response

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

HTTP Status Codes

Code	Description
200	OK - Request successful
201	Created - Resource created successfully
204	No Content - Resource deleted successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Rate Limiting

• Default: 100 requests per 15 minutes per IP
• Authenticated: 1000 requests per 15 minutes per user
• Admin: Unlimited

Rate limit headers:

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

Pagination

Endpoints returning lists support pagination:

GET /contests?limit=20&offset=0

Parameters:

• limit (default: 20, max: 100) - Number of items per page
• offset (default: 0) - Number of items to skip

Filtering & Sorting

Filtering

GET /contests?platform=codeforces&phase=BEFORE&difficulty=MEDIUM

Sorting

GET /contests?sortBy=startTime&sortOrder=asc

Parameters:

• sortBy - Field to sort by (e.g., startTime, createdAt)
• sortOrder - Sort direction: asc or desc

Search

Full-text search on supported endpoints:

GET /contests/search?q=educational

Timestamps

All timestamps are in ISO 8601 format (UTC):

2025-01-01T12:00:00.000Z

Enums

ContestPlatform

enum ContestPlatform {
  CODEFORCES = 'codeforces',
  LEETCODE = 'leetcode',
  CODECHEF = 'codechef',
  ATCODER = 'atcoder'
}

ContestPhase

enum ContestPhase {
  BEFORE = 'BEFORE',
  CODING = 'CODING',
  FINISHED = 'FINISHED'
}

DifficultyLevel

enum DifficultyLevel {
  BEGINNER = 'BEGINNER',
  EASY = 'EASY',
  MEDIUM = 'MEDIUM',
  HARD = 'HARD',
  EXPERT = 'EXPERT'
}

UserRole

enum UserRole {
  USER = 'user',
  ADMIN = 'admin'
}

API Modules

Authentication

• Sign Up - Create new user account
• Sign In - Authenticate user
• Refresh Token - Get new access token
• Sign Out - Invalidate tokens

Users

• Get Profile - Get current user profile
• Update Profile - Update user information
• Delete Account - Delete user account

Contests

• List Contests - Get all contests with pagination
• Get Contest - Get contest by ID
• Filter by Platform - Platform-specific contests
• Upcoming Contests - Get upcoming contests
• Running Contests - Get active contests
• Finished Contests - Get past contests
• Search Contests - Full-text search
• Contest Statistics - Analytics and insights
• Sync Contests - Trigger platform sync (admin)

Notifications

• Get Notifications - List user notifications
• Mark as Read - Mark notification as read
• Test Email - Send test email notification

Examples

cURL

# Login
curl -X POST http://localhost:3000/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

# Get contests
curl -X GET http://localhost:3000/contests \
  -H "Authorization: Bearer <access_token>"

JavaScript (Fetch)

// Login
const response = await fetch('http://localhost:3000/auth/signin', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});
const { accessToken } = await response.json();

// Get contests
const contests = await fetch('http://localhost:3000/contests', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

Python (Requests)

import requests

# Login
response = requests.post('http://localhost:3000/auth/signin', json={
    'email': 'user@example.com',
    'password': 'password123'
})
access_token = response.json()['accessToken']

# Get contests
contests = requests.get('http://localhost:3000/contests', headers={
    'Authorization': f'Bearer {access_token}'
})

Webhooks

Subscribe to real-time events:

• contest.created - New contest added
• contest.starting - Contest starting soon
• contest.finished - Contest ended
• notification.sent - Notification delivered

Support

• Documentation: https://docs.codenotify.dev
• GitHub: https://github.com/Celestial-0/codenotify
• Issues: https://github.com/Celestial-0/codenotify/issues

Changelog

v0.1.0-beta (2026-01-06)

• Initial beta release
• Auto-login after email verification
• Centralized version management
• Dynamic GitHub-based changelog