API Documentation

Complete reference for the Roskov API endpoints

View Endpoints Quick Start

Quick Start

Get started with the Roskov API

Authentication

The API uses JWT (JSON Web Tokens) for authentication. After registering or logging in, you'll receive an access token and refresh token.

Example: Register a new user
POST /api/auth/register/
Content-Type: application/json

{
  "username": "newuser",
  "password": "securepassword",
  "email": "user@example.com"
}
Example: Login
POST /api/auth/login/
Content-Type: application/json

{
  "username": "newuser",
  "password": "securepassword"
}

Response:
{
  "user": {...},
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Making Authenticated Requests

Include the access token in the Authorization header for protected endpoints.

Example: Get current user
GET /api/auth/me/
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Response:
{
  "id": 1,
  "username": "newuser",
  "email": "user@example.com"
}
Example: Get random word pair
GET /api/word-pairs/random/

Response:
{
  "id": 1,
  "french_word": "bonjour",
  "russian_word": "здравствуйте",
  "category": "greetings",
  "level": 1,
  ...
}

API Endpoints

Complete list of available API endpoints

Authentication

POST /api/auth/register/

Register a new user account

POST /api/auth/login/

Login and receive JWT tokens

POST /api/auth/auto-create/

Automatically create a guest user

GET /api/auth/me/

Get current authenticated user (requires authentication)

POST /api/token/refresh/

Refresh JWT access token

Word Pairs

GET /api/word-pairs/

List all word pairs

GET /api/word-pairs/random/

Get a random word pair

GET /api/word-pairs/by-level/?level=1

Get word pairs by level (1-5)

GET /api/word-pairs/new-words/

Get words not yet practiced (requires authentication)

GET /api/word-pairs/difficult-words/

Get words with highest mistake probability (requires authentication)

GET /api/word-pairs/multiple-choice-options/?word_pair_id=1&direction=fr_to_ru

Get word pair with multiple choice options

Game & Progress

POST /api/game-attempts/submit_answer/

Submit an answer and get feedback (requires authentication)

GET /api/progress/

Get user progress (streaks, daily goals) (requires authentication)

GET /api/level-progress/

Get progress for all levels (requires authentication)

GET /api/current-level/

Get current active level (requires authentication)

GET /api/user-stats/summary/

Get summary statistics (requires authentication)

GET /api/rankings/

Get user rankings based on performance

Lessons

GET /api/lessons/

List all lessons

GET /api/lessons/by-level/?level=1

Get lessons by level

POST /api/lessons/{id}/complete/

Mark a lesson as completed (requires authentication)

System

GET /api/health/

Health check endpoint