API docs by Redocly

PeerPrep API (1.0.0)

Download OpenAPI specification:

License: Apache 2.0

These are the API endpoints for all PeerPrep microservices

user-service

Microservice for user management

Get current authenticated user

Returns the currently authenticated user's information. The user is identified by decoding the JWT access token from the jwt_access_token cookie.

Authorizations:
jwtTokensCookieAuth

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4e5",
  • "username": "johndoe",
  • "email": "johndoe@example.com",
  • "isAdmin": false,
  • "createdAt": "2025-11-04T15:23:00.000Z",
  • "updatedAt": "2025-11-04T15:23:00.000Z"
}

Get user by ID

Retrieves a user's profile information by their unique ID. Requires authentication via cookies.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string

The ID of the user to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4e5",
  • "username": "johndoe",
  • "email": "johndoe@example.com",
  • "isAdmin": false,
  • "createdAt": "2025-11-04T15:23:00.000Z",
  • "updatedAt": "2025-11-04T15:23:00.000Z"
}

Update user account

Updates user information (username, email, or password). At least one field must be updated. Requires the user's current password for verification.
Only the authenticated user can update their own account, authorized via request cookies.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string

The ID of the user to update.

Request Body schema: application/json
required
currentPassword
string <password>

The user's current password (required).

newPassword
string <password>

The new password (min. 3 characters).

newEmail
string <email>

The new email address.

newUsername
string

The new username.

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "oldPass123",
  • "newPassword": "newPass456",
  • "newEmail": "newmail@example.com",
  • "newUsername": "newusername"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4e5",
  • "username": "newusername",
  • "email": "newmail@example.com",
  • "isAdmin": false
}

Register a new user

Creates a new user account after validating input and ensuring the username and email are unique.

Request Body schema: application/json
required
username
required
string >= 3 characters

The desired username. Must be at least 3 characters long.

email
required
string <email> >= 3 characters

The user's email address.

password
required
string <password> >= 3 characters

The user's password. Must be at least 3 characters long.

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe",
  • "email": "johndoe@example.com",
  • "password": "mySecureP@ssw0rd"
}

Response samples

Content type
application/json
{
  • "id": "f1a2b3c4d5",
  • "username": "johndoe",
  • "email": "johndoe@example.com",
  • "isAdmin": false,
  • "createdAt": "2025-11-04T15:23:00.000Z",
  • "updatedAt": "2025-11-04T15:23:00.000Z"
}

Log in a user

Authenticates a user with email and password. Returns user info and sets access and refresh tokens in cookies.

Request Body schema: application/json
required
email
required
string <email>

The email address associated with the user account.

password
required
string <password>

The user's password.

Responses

Request samples

Content type
application/json
{
  • "email": "johndoe@example.com",
  • "password": "mySecureP@ssw0rd"
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4e5",
  • "username": "johndoe",
  • "email": "johndoe@example.com",
  • "isAdmin": false,
  • "createdAt": "2025-11-04T15:23:00.000Z",
  • "updatedAt": "2025-11-04T15:23:00.000Z"
}

Log out the current user

Logs out the currently authenticated user by removing the stored refresh token and clearing authentication cookies (jwt_access_token and jwt_refresh_token). This endpoint requires that the user is currently logged in.

Authorizations:
jwtTokensCookieAuth

Responses

Response samples

Content type
application/json
{
  • "message": "User logged out"
}

Refresh access token

Generates a new access token using a valid refresh token stored in the jwt_refresh_token cookie. The new access token is set as an HTTP-only cookie (jwt_access_token).

Authorizations:
jwtTokensCookieAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Access token refreshed"
}

attempt-service

Microservice for question attempt management

Create a new attempt

Creates a new attempt for a given collaboration and question. Requires authentication via the jwt_access_token cookie.

Authorizations:
jwtTokensCookieAuth
Request Body schema: application/json
required
collabId
required
string
questionId
required
number
content
required
string

Responses

Request samples

Content type
application/json
{
  • "collabId": "d5ed2f3b-942c-4543-a0d3-a6f57f4bf2b4",
  • "questionId": 42,
  • "content": "function add(a, b) { return a + b; }"
}

Response samples

Content type
application/json
{
  • "message": "Attempt created"
}

Get attempt by id.

Retrieves an attempt associated with the attempt id

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string

The attempt's unique ID.

Responses

Get attempts by user ID

Retrieves all attempts made by a specific user.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string
Example: d5ed2f3b-942c-4543-a0d3-a6f57f4bf2b4

The user's unique ID.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get unique question IDs attempted by user

Returns a list of unique question IDs that a specific user has attempted.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string
Example: user123

The user's unique ID.

Responses

Response samples

Content type
application/json
[
  • 42
]

question-service

Microservice for question management

List questions

Retrieves a list of questions with optional filters and pagination.

Authorizations:
jwtTokensCookieAuth
query Parameters
search
string
Example: search=binary search

Search by question title or statement.

topicNames
string
Example: topicNames=Arrays,Sorting

Comma-separated topic names to filter by.

difficulty
string
Example: difficulty=Easy,Medium

Filter by difficulty (single or comma-separated values).

orderBy
string
Enum: "newest" "oldest" "title"
Example: orderBy=newest

Sort order of results.

skip
integer
Example: skip=0

Number of results to skip.

take
integer
Example: take=25

Maximum number of results to return.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a new question

Create a new question with metadata, examples, and topics.

Authorizations:
jwtTokensCookieAuth
Request Body schema: application/json
required
title
required
string
statement
required
string
difficulty
required
string
Enum: "Easy" "Medium" "Hard"
topicNames
Array of strings
Array of objects (ExampleIO)
constraints
Array of strings
solutionOutline
required
string
metadata
object or null

Responses

Request samples

Content type
application/json
{
  • "title": "Two Sum",
  • "statement": "Find two numbers that add up to target.",
  • "difficulty": "Easy",
  • "topicNames": [
    ],
  • "exampleIO": [
    ],
  • "constraints": [
    ],
  • "solutionOutline": "Use a hash map.",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "title": "Two Sum",
  • "statement": "Find two numbers that add up to target.",
  • "difficulty": "Easy",
  • "topicNames": [
    ],
  • "exampleIO": [
    ],
  • "constraints": [
    ],
  • "solutionOutline": "Use a hash map to track complements.",
  • "metadata": {
    },
  • "createdAt": "2025-11-01T12:00:00Z"
}

Get question by ID

Retrieve a specific question by its numeric ID.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
integer
Example: 1

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "title": "Two Sum",
  • "statement": "Find two numbers that add up to target.",
  • "difficulty": "Easy",
  • "topicNames": [
    ],
  • "exampleIO": [
    ],
  • "constraints": [
    ],
  • "solutionOutline": "Use a hash map to track complements.",
  • "metadata": {
    },
  • "createdAt": "2025-11-01T12:00:00Z"
}

Update question (soft delete supported)

Updates fields of an existing question. If the question is marked as deleted, this performs a soft delete.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
integer
Example: 1
Request Body schema: application/json
required
title
required
string
statement
required
string
difficulty
required
string
Enum: "Easy" "Medium" "Hard"
topicNames
Array of strings
Array of objects (ExampleIO)
constraints
Array of strings
solutionOutline
required
string
metadata
object or null

Responses

Request samples

Content type
application/json
{
  • "title": "Two Sum",
  • "statement": "Find two numbers that add up to target.",
  • "difficulty": "Easy",
  • "topicNames": [
    ],
  • "exampleIO": [
    ],
  • "constraints": [
    ],
  • "solutionOutline": "Use a hash map.",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "title": "Two Sum",
  • "statement": "Find two numbers that add up to target.",
  • "difficulty": "Easy",
  • "topicNames": [
    ],
  • "exampleIO": [
    ],
  • "constraints": [
    ],
  • "solutionOutline": "Use a hash map to track complements.",
  • "metadata": {
    },
  • "createdAt": "2025-11-01T12:00:00Z"
}

Soft delete a question

Marks a question as deleted without permanently removing it.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
integer
Example: 1

Responses

Hard delete a question

Permanently removes a question from the database.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
integer
Example: 1

Responses

Response samples

Content type
application/json
{
  • "message": "Question permanently deleted",
  • "deleted": true
}

List available languages

Returns all programming languages supported by the platform.

Authorizations:
jwtTokensCookieAuth

Responses

Response samples

Content type
application/json
{
  • "count": 5,
  • "languages": [
    ]
}

List all topics

Returns all coding topics (e.g., Arrays, Graphs, DP).

Authorizations:
jwtTokensCookieAuth

Responses

Response samples

Content type
application/json
{
  • "count": 4,
  • "topics": [
    ]
}

Hard delete a topic

Permanently removes a topic.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
integer
Example: 10

Responses

Response samples

Content type
application/json
{
  • "message": "Topic permanently deleted",
  • "deleted": true
}

matching-service

Microservice for matching users

Request a match

Queues the user for a match or immediately returns a matched session if found. Requires user authentication.

Authorizations:
jwtTokensCookieAuth
Request Body schema: application/json
required
userId
string
string or Array of strings
string or Array of strings
string or Array of strings
ttlMs
integer

Time (ms) before the match request expires.

Responses

Request samples

Content type
application/json
{
  • "userId": "user123",
  • "languageIn": "JavaScript",
  • "difficultyIn": "Easy",
  • "topicIn": "Algorithms",
  • "ttlMs": 300000
}

Response samples

Content type
application/json
{
  • "status": "matched",
  • "roomId": "room789",
  • "topic": "Graphs",
  • "difficulty": "Medium",
  • "language": "Python",
  • "questionId": 42,
  • "userId": "user123",
  • "partnerId": "user456",
  • "subscribeUrl": "http://api.example.com/matching/subscribe/user123",
  • "session": {
    }
}

Get matchmaking status for a user

Returns the current matchmaking status (QUEUED, MATCHED, CANCELLED, or EXPIRED) for the given user.

Authorizations:
jwtTokensCookieAuth
path Parameters
userId
required
string
Example: user123

Responses

Response samples

Content type
application/json
{
  • "userId": "user123",
  • "status": "QUEUED",
  • "position": 2
}

Cancel a pending match

Cancels a matchmaking request for the given user.

Authorizations:
jwtTokensCookieAuth
Request Body schema: application/json
required
userId
string

Responses

Request samples

Content type
application/json
{
  • "userId": "user123"
}

Response samples

Content type
application/json
{
  • "userId": "user123",
  • "status": "CANCELLED"
}

Subscribe to matchmaking updates via SSE

Opens a Server-Sent Events (SSE) stream for real-time matchmaking updates. The stream sends the following events:

  • heartbeat: every 15s
  • MATCH_FOUND: when a match is found
  • TIMEOUT: if no match found before ttlMs expires
Authorizations:
jwtTokensCookieAuth
path Parameters
userId
required
string
Example: user123
query Parameters
ttlMs
integer
Example: ttlMs=30000
pollMs
integer
Example: pollMs=1000

Responses

Response samples

Content type
text/event-stream
event: heartbeat
data: {}
event: MATCH_FOUND
data: {"roomId":"room789","topic":"Graphs","difficulty":"Medium"}

Signal a match found event manually

Triggers a match notification for the given user, typically used internally by the system.

Authorizations:
jwtTokensCookieAuth
path Parameters
userId
required
string
Example: user123
Request Body schema: application/json
optional
roomId
string

Responses

Request samples

Content type
application/json
{
  • "roomId": "room789"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "delivered": 1,
  • "userId": "user123",
  • "roomId": "room789"
}

collab-service

Microservice for managing collaborative coding space

Health check

Authorizations:
jwtTokensCookieAuth

Responses

WebSocket upgrade for collaborative session

Creates a websocket connection to the hocuspocus backend that synchronizes Yjs documents between clients.

Authorizations:
jwtTokensCookieAuth

Responses

Get current user's active session

Retrieves a user's currently active session by the jwt_access_token in the request cookies.

Authorizations:
jwtTokensCookieAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get active session by username (unauthenticated, not secure)

Retrieves a user's currently active session by his username.

Authorizations:
jwtTokensCookieAuth
Request Body schema: application/json
required
username
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a new session

Creates a new collab session for 2 users after a successful match.

Authorizations:
jwtTokensCookieAuth
Request Body schema: application/json
required
topic
required
string
difficulty
required
string
questionId
required
string
id
string
expiresAt
string <date-time>
user1ID
string
user2ID
string
language
required
string
Enum: "java" "python"

Responses

Request samples

Content type
application/json
{
  • "topic": "string",
  • "difficulty": "string",
  • "questionId": "string",
  • "id": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "user1ID": "string",
  • "user2ID": "string",
  • "language": "java"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get session by ID

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

End session by ID

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Join a session

The user to join the session is identified from the jwt_access_token in the request cookies.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Leave a session

The user to leave the session is identified through the jwt_access_token in the request cookies.

Authorizations:
jwtTokensCookieAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Run session sweeper to expire old sessions

Authorizations:
jwtTokensCookieAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}