API reference

TECHDE API v1.0.0

Production-ready quiz platform backend: JWT auth with rotating refresh tokens, RBAC (guest / user / instructor / admin / super admin), quizzes, attempts, leaderboards, certificates, notifications, analytics, reports, audit trails and user tracking.

OpenAPI 3.0.3JWT access + rotating refresh tokensRBAC · guest → super_adminJSON · CSV reports

Auth

post/api/auth/register

Create an account and receive an access + refresh token pair

Request body

{
  "type": "object",
  "required": [
    "name",
    "email",
    "password"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 8
    }
  }
}

Responses

201 · Created400 · Validation error409 · Validation error429 · Rate limited

post/api/auth/login

Request body

{
  "type": "object",
  "required": [
    "email",
    "password"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string"
    }
  }
}

Responses

200 · Success401 · Missing or invalid access token429 · Rate limited

post/api/auth/refresh

Rotate a refresh token (old token is revoked, same family)

Request body

{
  "type": "object",
  "required": [
    "refreshToken"
  ],
  "properties": {
    "refreshToken": {
      "type": "string"
    }
  }
}

Responses

200 · Success401 · Missing or invalid access token429 · Rate limited

post/api/auth/logout

Revoke the presented refresh token and close its session

Request body

{
  "type": "object",
  "required": [
    "refreshToken"
  ],
  "properties": {
    "refreshToken": {
      "type": "string"
    }
  }
}

Responses

200 · Success401 · Missing or invalid access token

post/api/auth/logout-all Bearer

Revoke every refresh token for the signed-in user

Responses

200 · Success401 · Missing or invalid access token

get/api/auth/me Bearer

Fetch the current user from the access token

Responses

200 · Success401 · Missing or invalid access token

Content

get/api/categories

List categories with quiz counts (cached)

Responses

200 · Success

get/api/quizzes

Browse quizzes with search / category / difficulty / sort / pagination

Parameters

`id`	query	Fetch a single full quiz by id	string
`search`	query		string
`category`	query		string
`difficulty`	query	(easy, medium, hard)	string
`sort`	query	(popular, newest, rating, title)	string
`page`	query		integer
`pageSize`	query		integer

Responses

200 · Success404 · Resource not found

get/api/quizzes/{id}/play

Fetch a quiz for playing (answers stripped)

Parameters

idrequired path string

Responses

200 · Success404 · Resource not found

post/api/quizzes/{id}/rate

Rate a quiz 1–5 stars. Registered users get one vote per account; guests one per IP. The quiz's displayed rating blends these votes with the performance-derived rating.

Request body

{
  "type": "object",
  "required": [
    "rating"
  ],
  "properties": {
    "rating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    }
  }
}

Responses

200 · Success400 · Validation error404 · Resource not found429 · Rate limited

get/api/quizzes/{id}/rate

The caller's own rating for a quiz (null when they haven't voted)

Responses

200 · Success

Attempts

post/api/attempts

Submit a quiz attempt — registered and guest attempts persist, roll the quiz's plays/rating/average score, and capture IP + location

Request body

{
  "type": "object",
  "required": [
    "quizId",
    "answers",
    "durationSeconds"
  ],
  "properties": {
    "quizId": {
      "type": "string"
    },
    "durationSeconds": {
      "type": "integer",
      "minimum": 0
    },
    "answers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "questionId": {
            "type": "string"
          },
          "selectedOptionIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

200 · Success404 · Resource not found429 · Rate limited

Leaderboard

get/api/leaderboard

Rankings — global or per quiz, filtered by period

Parameters

`scope`	query	(global, quiz)	string
`quizId`	query		string
`period`	query	(all, week, month)	string
`limit`	query		integer

Responses

200 · Success400 · Validation error

Certificates

get/api/certificates/verify

Verify a certificate by its code

Parameters

coderequired query string

Responses

200 · Success404 · Resource not found

User

get/api/users/me/dashboard Bearer

Dashboard data: stats, attempts, bookmarks, certificates, achievements

Responses

200 · Success401 · Missing or invalid access token

get/api/users/me/attempts Bearer

List the signed-in user's attempts

Responses

200 · Success401 · Missing or invalid access token

get/api/users/me/bookmarks Bearer

List the signed-in user's bookmarks

Responses

200 · Success401 · Missing or invalid access token

post/api/users/me/bookmarks/{quizId} Bearer

Toggle a bookmark for a quiz

Parameters

quizIdrequired path string

Responses

200 · Success401 · Missing or invalid access token404 · Resource not found

get/api/users/me/certificates Bearer

List the signed-in user's certificates

Responses

200 · Success401 · Missing or invalid access token

Notifications

get/api/notifications Bearer

List notifications + unread count

Parameters

limit query integer

Responses

200 · Success401 · Missing or invalid access token

post/api/notifications Bearer

Broadcast a notification to every user (staff)

Request body

{
  "type": "object",
  "required": [
    "title",
    "body"
  ],
  "properties": {
    "title": {
      "type": "string"
    },
    "body": {
      "type": "string"
    },
    "link": {
      "type": "string"
    }
  }
}

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

post/api/notifications/read Bearer

Mark one notification (id) or all (all: true) as read

Request body

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "all": {
      "type": "boolean"
    }
  }
}

Responses

200 · Success400 · Validation error401 · Missing or invalid access token

Admin

get/api/admin/stats Bearer

Aggregate admin statistics (cached)

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

get/api/admin/analytics Bearer

Deep analytics: retention, difficulty mix, geography, per-day/per-quiz/per-category, top users & quizzes

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

get/api/admin/attempts Bearer

List every attempt (registered + guest) with user, quiz, IP and location

Parameters

limit query integer

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

get/api/admin/guests Bearer

Anonymous visitor analytics — per-device breakdown, locations, top quizzes, recent guest attempts

Parameters

guestId query A guest device id (e.g. `guest-a1b2c3d4e5`) to view one visitor's full attempt history string

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

get/api/admin/users Bearer

List all users

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

put/api/admin/users/{id} Bearer

Update a user's role (audited)

Parameters

idrequired path string

Request body

{
  "type": "object",
  "required": [
    "role"
  ],
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "user",
        "instructor",
        "admin",
        "super_admin"
      ]
    }
  }
}

Responses

200 · Success400 · Validation error403 · Insufficient role for this resource

delete/api/admin/users/{id} Bearer

Delete a user (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

get/api/admin/quizzes Bearer

List quizzes (staff view)

Responses

200 · Success403 · Insufficient role for this resource

post/api/admin/quizzes Bearer

Create a quiz with questions (audited)

Request body

{
  "type": "object",
  "required": [
    "title",
    "categoryId"
  ],
  "properties": {
    "title": {
      "type": "string"
    },
    "categoryId": {
      "type": "string"
    }
  }
}

Responses

201 · Created400 · Validation error403 · Insufficient role for this resource

get/api/admin/quizzes/{id} Bearer

Fetch a full quiz (with questions)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

put/api/admin/quizzes/{id} Bearer

Update a quiz (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

delete/api/admin/quizzes/{id} Bearer

Delete a quiz and its questions (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

get/api/admin/questions Bearer

List questions (optionally filtered by quizId)

Responses

200 · Success403 · Insufficient role for this resource

post/api/admin/questions Bearer

Create a question (audited)

Responses

201 · Created400 · Validation error403 · Insufficient role for this resource

put/api/admin/questions/{id} Bearer

Update a question (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

delete/api/admin/questions/{id} Bearer

Delete a question (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

get/api/admin/categories Bearer

List categories (staff view)

Responses

200 · Success403 · Insufficient role for this resource

post/api/admin/categories Bearer

Create a category (audited)

Responses

201 · Created400 · Validation error403 · Insufficient role for this resource

put/api/admin/categories/{id} Bearer

Update a category (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

delete/api/admin/categories/{id} Bearer

Delete a category (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

get/api/admin/reports Bearer

Export a report (attempts / users / quizzes / activity) as JSON or CSV

Parameters

`type`required	query	(attempts, users, quizzes, activity)	string
`format`	query	(json, csv)	string
`from`	query		string
`to`	query		string

Responses

200 · Success400 · Validation error403 · Insufficient role for this resource

get/api/admin/audit-logs Bearer

List recent audit log entries (staff actions)

Parameters

limit query integer

Responses

200 · Success403 · Insufficient role for this resource

Docs

get/api/docs/openapi.json

This OpenAPI specification

Responses

200 · Success

API reference

TECHDE API v1.0.0

OpenAPI 3.0.3JWT access + rotating refresh tokensRBAC · guest → super_adminJSON · CSV reports

Auth

post/api/auth/register

Create an account and receive an access + refresh token pair

Request body

{
  "type": "object",
  "required": [
    "name",
    "email",
    "password"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 8
    }
  }
}

Responses

201 · Created400 · Validation error409 · Validation error429 · Rate limited

post/api/auth/login

Request body

{
  "type": "object",
  "required": [
    "email",
    "password"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string"
    }
  }
}

Responses

200 · Success401 · Missing or invalid access token429 · Rate limited

post/api/auth/refresh

Rotate a refresh token (old token is revoked, same family)

Request body

{
  "type": "object",
  "required": [
    "refreshToken"
  ],
  "properties": {
    "refreshToken": {
      "type": "string"
    }
  }
}

Responses

200 · Success401 · Missing or invalid access token429 · Rate limited

post/api/auth/logout

Revoke the presented refresh token and close its session

Request body

{
  "type": "object",
  "required": [
    "refreshToken"
  ],
  "properties": {
    "refreshToken": {
      "type": "string"
    }
  }
}

Responses

200 · Success401 · Missing or invalid access token

post/api/auth/logout-all Bearer

Revoke every refresh token for the signed-in user

Responses

200 · Success401 · Missing or invalid access token

get/api/auth/me Bearer

Fetch the current user from the access token

Responses

200 · Success401 · Missing or invalid access token

Content

get/api/categories

List categories with quiz counts (cached)

Responses

200 · Success

get/api/quizzes

Browse quizzes with search / category / difficulty / sort / pagination

Parameters

`id`	query	Fetch a single full quiz by id	string
`search`	query		string
`category`	query		string
`difficulty`	query	(easy, medium, hard)	string
`sort`	query	(popular, newest, rating, title)	string
`page`	query		integer
`pageSize`	query		integer

Responses

200 · Success404 · Resource not found

get/api/quizzes/{id}/play

Fetch a quiz for playing (answers stripped)

Parameters

idrequired path string

Responses

200 · Success404 · Resource not found

post/api/quizzes/{id}/rate

Rate a quiz 1–5 stars. Registered users get one vote per account; guests one per IP. The quiz's displayed rating blends these votes with the performance-derived rating.

Request body

{
  "type": "object",
  "required": [
    "rating"
  ],
  "properties": {
    "rating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    }
  }
}

Responses

200 · Success400 · Validation error404 · Resource not found429 · Rate limited

get/api/quizzes/{id}/rate

The caller's own rating for a quiz (null when they haven't voted)

Responses

200 · Success

Attempts

post/api/attempts

Submit a quiz attempt — registered and guest attempts persist, roll the quiz's plays/rating/average score, and capture IP + location

Request body

{
  "type": "object",
  "required": [
    "quizId",
    "answers",
    "durationSeconds"
  ],
  "properties": {
    "quizId": {
      "type": "string"
    },
    "durationSeconds": {
      "type": "integer",
      "minimum": 0
    },
    "answers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "questionId": {
            "type": "string"
          },
          "selectedOptionIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Responses

200 · Success404 · Resource not found429 · Rate limited

Leaderboard

get/api/leaderboard

Rankings — global or per quiz, filtered by period

Parameters

`scope`	query	(global, quiz)	string
`quizId`	query		string
`period`	query	(all, week, month)	string
`limit`	query		integer

Responses

200 · Success400 · Validation error

Certificates

get/api/certificates/verify

Verify a certificate by its code

Parameters

coderequired query string

Responses

200 · Success404 · Resource not found

User

get/api/users/me/dashboard Bearer

Dashboard data: stats, attempts, bookmarks, certificates, achievements

Responses

200 · Success401 · Missing or invalid access token

get/api/users/me/attempts Bearer

List the signed-in user's attempts

Responses

200 · Success401 · Missing or invalid access token

get/api/users/me/bookmarks Bearer

List the signed-in user's bookmarks

Responses

200 · Success401 · Missing or invalid access token

post/api/users/me/bookmarks/{quizId} Bearer

Toggle a bookmark for a quiz

Parameters

quizIdrequired path string

Responses

200 · Success401 · Missing or invalid access token404 · Resource not found

get/api/users/me/certificates Bearer

List the signed-in user's certificates

Responses

200 · Success401 · Missing or invalid access token

Notifications

get/api/notifications Bearer

List notifications + unread count

Parameters

limit query integer

Responses

200 · Success401 · Missing or invalid access token

post/api/notifications Bearer

Broadcast a notification to every user (staff)

Request body

{
  "type": "object",
  "required": [
    "title",
    "body"
  ],
  "properties": {
    "title": {
      "type": "string"
    },
    "body": {
      "type": "string"
    },
    "link": {
      "type": "string"
    }
  }
}

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

post/api/notifications/read Bearer

Mark one notification (id) or all (all: true) as read

Request body

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "all": {
      "type": "boolean"
    }
  }
}

Responses

200 · Success400 · Validation error401 · Missing or invalid access token

Admin

get/api/admin/stats Bearer

Aggregate admin statistics (cached)

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

get/api/admin/analytics Bearer

Deep analytics: retention, difficulty mix, geography, per-day/per-quiz/per-category, top users & quizzes

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

get/api/admin/attempts Bearer

List every attempt (registered + guest) with user, quiz, IP and location

Parameters

limit query integer

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

get/api/admin/guests Bearer

Anonymous visitor analytics — per-device breakdown, locations, top quizzes, recent guest attempts

Parameters

guestId query A guest device id (e.g. `guest-a1b2c3d4e5`) to view one visitor's full attempt history string

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

get/api/admin/users Bearer

List all users

Responses

200 · Success401 · Missing or invalid access token403 · Insufficient role for this resource

put/api/admin/users/{id} Bearer

Update a user's role (audited)

Parameters

idrequired path string

Request body

{
  "type": "object",
  "required": [
    "role"
  ],
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "user",
        "instructor",
        "admin",
        "super_admin"
      ]
    }
  }
}

Responses

200 · Success400 · Validation error403 · Insufficient role for this resource

delete/api/admin/users/{id} Bearer

Delete a user (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

get/api/admin/quizzes Bearer

List quizzes (staff view)

Responses

200 · Success403 · Insufficient role for this resource

post/api/admin/quizzes Bearer

Create a quiz with questions (audited)

Request body

{
  "type": "object",
  "required": [
    "title",
    "categoryId"
  ],
  "properties": {
    "title": {
      "type": "string"
    },
    "categoryId": {
      "type": "string"
    }
  }
}

Responses

201 · Created400 · Validation error403 · Insufficient role for this resource

get/api/admin/quizzes/{id} Bearer

Fetch a full quiz (with questions)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

put/api/admin/quizzes/{id} Bearer

Update a quiz (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

delete/api/admin/quizzes/{id} Bearer

Delete a quiz and its questions (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

get/api/admin/questions Bearer

List questions (optionally filtered by quizId)

Responses

200 · Success403 · Insufficient role for this resource

post/api/admin/questions Bearer

Create a question (audited)

Responses

201 · Created400 · Validation error403 · Insufficient role for this resource

put/api/admin/questions/{id} Bearer

Update a question (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

delete/api/admin/questions/{id} Bearer

Delete a question (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

get/api/admin/categories Bearer

List categories (staff view)

Responses

200 · Success403 · Insufficient role for this resource

post/api/admin/categories Bearer

Create a category (audited)

Responses

201 · Created400 · Validation error403 · Insufficient role for this resource

put/api/admin/categories/{id} Bearer

Update a category (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

delete/api/admin/categories/{id} Bearer

Delete a category (audited)

Parameters

idrequired path string

Responses

200 · Success403 · Insufficient role for this resource404 · Resource not found

get/api/admin/reports Bearer

Export a report (attempts / users / quizzes / activity) as JSON or CSV

Parameters

`type`required	query	(attempts, users, quizzes, activity)	string
`format`	query	(json, csv)	string
`from`	query		string
`to`	query		string

Responses

200 · Success400 · Validation error403 · Insufficient role for this resource

get/api/admin/audit-logs Bearer

List recent audit log entries (staff actions)

Parameters

limit query integer

Responses

200 · Success403 · Insufficient role for this resource

Docs

get/api/docs/openapi.json

This OpenAPI specification

Responses

200 · Success