Guide

Study Options

Session size limit

When you have many cards due, you can limit your session to a fixed number of cards. This is shown prominently at the top of the study page.

• Enter a number (e.g. 20 or 50) in the Session size input to cap how many unique cards you review.
• Cards you grade as "Again" will loop back within the session — they don't count against your limit twice.
• When you finish the session, you'll see a "Session complete!" screen with a Continue reviewing button to start another batch.
• If you rated any cards Again or Hard, a Review weak cards button appears letting you immediately re-review only those cards before moving on.
• Leave the field empty (or clear filters) to review all due cards with no limit.
• Your session size is remembered across page reloads (stored in session storage).

Tip: Combine session size with tag or state filters. For example, filter by a tag with 100+ words and set session size to 20 to review in manageable chunks.

Review filters

Below the session size, you can filter by tags, state (New/Learning/Review), or mode (Due only vs. all cards). Filters and session size work together — for example, you can review only "New" cards from a specific tag, limited to 15 per session.

Reverse mode

Check the Reverse toggle in the filter bar to flip the card direction: the translation is shown on the front and you recall the foreign word. This is useful for practicing active recall (L1 → L2). Reverse mode works with all other filters and persists across page reloads via the URL.

Study Time Analytics

The Progress page tracks how much time you spend studying:

• Today's study time and number of sessions
• All-time total study time across all sessions
• Total sessions — each visit to the Study page that includes at least one card review counts as a session
• Average session length and average cards per session
• Total reviews — cumulative count of all card reviews ever

Sessions are tracked automatically. The Study page starts a timer when you begin, and saves the session when you finish or leave the page.

Charts

• Daily Reviews (30 days) — a bar chart showing how many reviews you did each day. Helps you see study consistency
• Due Forecast (7 days) — a strip showing how many cards will be due each upcoming day. Useful for planning when to study

Interpreting Your Retention Rate

• 90%+ — excellent. FSRS is scheduling optimally and your memory is strong
• 80-90% — good. Consider reviewing more frequently or reducing new cards per day
• Below 80% — you may be adding too many new cards or not reviewing often enough. Focus on clearing your due queue before adding new words

Importing Words

Words on Repeat provides an Import button on both the Vocabulary page and each deck card on the Decks page. Click it to open the import modal.

The import modal has two tabs:

• Upload File — select a .json file from your computer
• Paste JSON — paste JSON directly (great for AI-generated output)

Word fields (strict validation)

The import modal performs strict field validation. Only the following field names are accepted — any unknown fields will be rejected with an error showing the allowed fields:

Example JSON:

[
  {
    "word": "Disparar",
    "translation": "To skyrocket",
    "example_sentence": "Lidl dispara su beneficio en España.",
    "example_translation": "Lidl's profit is skyrocketing in Spain.",
    "tags": "business,B2"
  }
]

Common mistakes: Using definition instead of translation, context instead of example_sentence, or camelCase names like exampleSentence. The validation will catch these and show you the correct field names.

Both tabs accept two JSON formats:

• Bare array: [{ "word": "...", "translation": "..." }]
• Wrapped: { "words": [{ "word": "...", "translation": "..." }] }

Tags on import: Enter comma-separated tags in the "Tags to apply" field. These tags are applied to any imported words that don't already have tags set in the JSON. Words that already have tags in the JSON keep their original tags.

Duplicate handling: After importing, you'll see:

1. How many words were successfully created
2. A list of any duplicates that were skipped (case-insensitive match on the word text)
3. An "Import anyway" button to force-add the duplicates as separate entries

Typical use cases:

• Paste AI-generated vocabulary from Claude or ChatGPT
• Upload a previously exported JSON backup
• Transfer words between decks (export from one, import to another)
• Bulk-add vocabulary from a textbook or word list

Daily Study Goals

You can set a daily study goal for each deck to stay consistent with your reviews.

• Where to set goals: Go to the Settings page, or click the pencil icon on the Study setup screen to edit your goal inline.
• Per-deck: Each deck has its own independent goal. Switching decks shows the goal for that deck.
• What it tracks: Total cards reviewed (all grades count). Re-reviews of cards graded "Again" within the same session don't double-count.
• Where progress shows: Nav bar indicator, Study setup page, session summary, and the Progress page banner.
• Soft goal: Goals never block studying — they're purely motivational. You can always review more or fewer cards than your goal.
• Disable: Set the goal to 0 to turn it off for a deck.

Push Notifications

Words on Repeat can send you a daily push notification when you have cards due for review.

• What's sent: A single daily reminder like "You have X cards waiting" — only when you have due cards.
• When: Once per day (server-side, default 9 AM UTC).
• How to enable: Go to Settings → Notifications → Enable, or click "Enable" on the dashboard prompt.
• How to disable: Go to Settings → Notifications → Disable, or use your browser's notification settings.
• Requirements: HTTPS, a browser with Push API support, and an active service worker.
• Max frequency: At most once per 20 hours, and only if you have due cards.
• No marketing: We only send study reminders — never promotional or marketing messages.

Install as App (PWA)

Words on Repeat is a Progressive Web App (PWA) that can be installed on your phone or desktop for a native-like experience.

• Install prompt: An install banner appears automatically when you visit the app in a compatible browser.
• Manual install: Use your browser menu → "Add to Home Screen" or "Install App".
• Offline: Static pages (CSS, JS, icons) are cached for fast loading. Study and vocabulary features require an internet connection for data sync.
• Benefit: Runs in its own window, no browser chrome, quick access from your home screen or taskbar.

Appearance (Light / Dark Mode)

You can toggle between light and dark themes to suit your preference.

• Toggle: Click the sun/moon icon in the nav bar, or go to Settings → Appearance.
• Three options: Light, Dark, or System (follows your OS preference).
• Default: Dark mode.
• Persistence: Your preference is saved in localStorage and restored on every visit.
• Cross-tab sync: Changing the theme in one tab syncs across all open tabs.

Understanding FSRS Details

Click the "Details" button on any word in the Vocabulary page to see its FSRS memory metrics. Here's what each metric means:

The FSRS Algorithm

Why FSRS

Words on Repeat uses FSRS (Free Spaced Repetition Scheduler) — the most accurate open-source spaced repetition algorithm available today. Created by Jarrett Ye and backed by peer-reviewed research published at ACM KDD 2022 and IEEE TKDE 2023, FSRS represents a generational leap over the 37-year-old SM-2 algorithm still used as Anki's default.

The core promise: FSRS achieves 20-30% fewer reviews than SM-2 at the same retention rate, or higher retention with the same number of reviews. This is validated across 727 million reviews from 10,000 users in the largest spaced repetition benchmark ever conducted.

How FSRS Works

FSRS models human memory using three core variables:

These three variables (the DSR model) work together to determine when to schedule each card. After each review, FSRS recalculates stability based on your grade:

The forgetting curve: FSRS models forgetting as a power function — more accurate than the exponential decay used by older algorithms. Your retrievability decreases over time after each review:

Key insight: The harder the card is for you specifically, the shorter the interval. The easier, the longer. This is personalized per card based on your review history.

FSRS vs SM-2 (Anki)

SM-2 was created in 1987. It's simple but has fundamental limitations by modern standards.

The "Ease Hell" problem in SM-2: Once a card's ease factor drops to the minimum (130%), it never recovers with normal use. The card appears too frequently, wasting your time forever. FSRS solves this with mean reversion — after consecutive correct answers, difficulty naturally decreases back toward baseline.

Benchmark Results

From the open-spaced-repetition benchmark — the largest SRS evaluation ever conducted (727 million reviews, 10,000 users):

What this means in practice:

• FSRS predicts with high accuracy when you'll forget each card
• It schedules reviews at the mathematically optimal moment
• You review only when needed — no wasted sessions on cards you already know
• Difficult cards get more attention; easy cards get longer breaks

Import & Export

Go to Settings to import and export words for the active deck.

Export

Downloads all words from the active deck as a JSON file, including FSRS scheduling state. You can optionally filter by tag using the dropdown before clicking Export.

Import

Select a JSON file to import words. The import flow includes duplicate detection:

1. Words that already exist in the deck (case-insensitive match) are skipped by default and listed.
2. If duplicates are found, you'll see an "Import duplicates anyway" button to add them as separate entries.
3. Words without FSRS data are imported as new cards. Words with FSRS data (from a previous export) retain their scheduling state.

Migrate from Quizlet

You can bring your Quizlet study sets into Words on Repeat using the built-in Quizlet import format.

Method 1: Copy & paste (easiest)

1. Open your Quizlet study set
2. Click the three dots (...) → Export
3. Set separator to Tab between term and definition
4. Set rows separated by New line
5. Click Copy text
6. In Words on Repeat, open a deck and click Import
7. Select the Quizlet format tab → switch to Paste Text
8. Paste the copied text and click Import

Your cards are immediately available for study with FSRS scheduling.

Note: Quizlet may require a paid plan to access the Export feature. If the export option isn't available, try Method 2.

Method 2: Use curated decks instead

If you were studying a language on Quizlet with community-made sets, the curated deck library may be a better starting point. Community Quizlet sets often have typos and no example sentences. The official Words on Repeat decks include grammar notes, example sentences with translations, and follow CEFR vocabulary standards.

For a detailed comparison of Quizlet vs Words on Repeat, see the full migration guide on the blog.

Deck Sharing

You can share your decks with other Words on Repeat users. Shared users get read-only access to view the deck and its words.

How to share a deck

1. Go to the Decks page
2. Click the Share button on any deck you own
3. Enter the email address of the user you want to share with
4. The deck will appear in their deck list marked as a shared deck

What shared users can do

The deck owner can unshare at any time by clicking the share button again and removing the user. Sharing is per-user — each user must be added individually.

Use cases: Teachers sharing vocabulary lists with students, study groups using the same word sets, or creating a "master deck" for new users to reference.

Settings & API Keys

The Settings page provides account management and programmatic access.

API Keys

API keys allow external tools (scripts, AI assistants like Claude or ChatGPT) to read and write words and decks programmatically.

1. Click "Generate Key" and enter an optional label
2. The raw key is shown — click Copy to copy it to your clipboard, or Show to reveal it
3. Use in HTTP requests: Authorization: Bearer sk_your_key_here
4. Keys can be revoked at any time

Note: Only users with the api_user or admin role can create API keys. If you don't see the API Keys section, ask your admin to grant you the api_user role.

API keys can read/write words and decks but cannot perform destructive operations (deck delete, password change) or access study/progress endpoints — those require browser login.

Appearance

Choose your preferred theme: Light, Dark, or System (follows your OS setting). You can also toggle the theme using the sun/moon icon in the nav bar.

Notifications

Enable or disable daily push notification reminders. When enabled, you'll receive a notification when you have cards due for review. See the Push Notifications section for details.

Daily Study Goal

Set a daily review target for the active deck. See Daily Study Goals for details.

Change Password

Enter your current password and a new password (minimum 8 characters) to update your login credentials.

Import / Export (Settings page)

The Settings page also provides import/export for the active deck, with optional tag filtering on export. This is in addition to the Import modal available on the Vocabulary and Decks pages.

Admin & User Management

Admins can manage user accounts from the Admin page, accessible via Settings > User Management.

Roles

Each user can have one or more roles. Roles control what features are available:

Users can have multiple roles at once (e.g., user + api_user).

Account Security

Words on Repeat includes several security measures to protect your account and data:

• Password hashing — passwords are stored as bcrypt hashes, not plain text
• Minimum password length — 8 characters enforced on all password operations
• Account lockout — after 3 consecutive failed login attempts, the account is automatically locked. An admin must unlock it from the Admin panel by setting the status back to "active"
• JWT security — tokens have 7-day expiry, stored in httpOnly cookies with sameSite strict (prevents CSRF attacks)
• API key security — keys are stored as SHA256 hashes in the database. The raw key (sk_...) is shown only once at creation time. Use the Copy button to save it
• Role-based access — destructive operations require JWT login (not API keys). Admin operations require the admin role. API key creation requires api_user or admin
• Inactive accounts — admins can set a user's status to "inactive" to prevent login without deleting their data

Deck Types

Words on Repeat supports two deck types:

• Language decks — The default type. Each card has a word and translation with optional example sentences. Requires source and target language (e.g., Spanish → English).
• Generic decks — For non-language content. Each card has a front and back instead of word/translation. Use for history, science, exam prep, or any topic. Set an optional subject field to describe the topic.

Choose the deck type when creating a new deck. The study experience, FSRS scheduling, and all features work identically for both types — only the labels change.

Card Types

Each word/card can be one of three types:

Cloze format: Store the sentence in the word field as The {{c1::cat::animal}} sat on the mat. During study, it displays as "The [animal] sat on the mat". Tap to reveal the answer.

MC format: Provide 2-6 options when adding the card. The first option is the correct answer (shuffled during study). Selecting the correct answer auto-grades as Good; wrong answers auto-grade as Again.

Study Modes

Words on Repeat offers three ways to study your cards during a review session:

All three modes use FSRS scheduling and work with tag filters, state filters, and session size limits. Reverse and Recall can be combined with any other filter.

Deck scheduling modes

Each deck also has a scheduling mode that controls whether cards appear in the study queue:

• Active (default) — Normal FSRS scheduling. Cards appear when due.
• Paused — Deck is visible but cards never appear in the study queue. Due count shows as 0. Use for decks you want to take a break from.
• Reference — Cards can be browsed (next/previous) but no FSRS grades are recorded. Use for completed decks you want to look up.

Change the scheduling mode from the deck edit modal. Switching from Paused back to Active makes all overdue cards immediately available.

AI Content Extraction

Extract vocabulary from any content source using AI. Navigate to the AI Extract page from the nav menu.

How it works

1. Choose a source — Three tabs: paste text, enter a URL, or upload a file (TXT, PDF, DOCX)
2. AI extracts vocabulary — The AI reads your content and returns vocabulary words with translations, example sentences, and example translations
3. Preview and edit — Review the extracted cards in a table. Edit, delete, or add cards before saving
4. Confirm — Save the cards to your active deck. They start as new FSRS cards

Tier limits

AI Exercises

Generate practice exercises from your existing deck words. The AI creates new study material in three formats:

• Cloze — AI creates a sentence with the target word blanked out
• Multiple Choice — AI generates 3 plausible distractors for each word
• Q&A — AI reformulates the word/translation as a question and answer

Free users get 1 exercise generation per day. Pro gets 10/day. Pro Max gets 30/day. Pro and Pro Max users can save generated exercises as new cards in the deck.

Daily Context Sentences

Each day, the AI generates a natural sentence using 3-5 of your recently studied words. This helps you see vocabulary used in context and reinforces memory through meaningful connections.

The sentence is cached for the day (one per deck). Pro Max users can regenerate with different styles: formal, casual, story, or dialogue. Access daily sentences from the study page at the start of each session.

YouTube Import

Import vocabulary from YouTube video subtitles. Available on Pro (3/day) and Pro Max (5/day).

1. Navigate to the AI Extract page
2. Paste a YouTube video URL (standard watch URLs, short links, and embed URLs supported)
3. The system fetches subtitles (auto-generated or manual captions)
4. AI extracts vocabulary from the subtitle text using the same extraction pipeline
5. Preview, edit, and save cards to your deck

Works with any language that has captions available on the video.

Smart Duplicate Detection

When adding words or importing vocabulary, the system checks for duplicates at up to three levels:

When a duplicate is detected, you see a warning with the match level. You can choose to add the word anyway or skip it.

Quiz Games

Four game modes for testing your vocabulary. Navigate to the Quiz page from the nav menu. All games require at least 4 words in the deck.

• Match — Tap word-translation pairs to match them. Pairs disappear when correctly matched.
• Write — See the translation, type the word from memory. Includes a first-letter hint.
• Multiple Choice — Answer MC questions generated from your deck words. 4 options per question.
• Race — Timed match game with a countdown. Score based on speed and accuracy.

Quiz games don't call AI — they generate questions from your existing deck data.

Test Export

Export printable vocabulary tests in two formats:

• HTML (all tiers) — Clean printable page with questions. Open in browser and print.
• PDF (Pro+) — A4 document with questions and an optional answer key on a separate page.

Anki Import/Export

Import and export Anki deck packages (.apkg files). Available on Pro and Pro Max.

Import

1. Click Import Anki on the Decks page
2. Upload a .apkg file
3. Preview the extracted notes (front/back fields)
4. Choose to create a new deck or add to an existing one
5. Confirm to save all cards

Export

Click Export Anki on the Vocabulary page to download your deck as a .apkg file. Pro Max exports include FSRS scheduling metadata so your review history transfers to Anki.

Free users can still import and export vocabulary via JSON.

Browser Extension

The Words on Repeat Chrome extension lets you save vocabulary from any webpage.

• Double-click any word on a webpage to see a save tooltip
• Right-click selected text and choose "Save to Words on Repeat"
• Auto-translate — click the translate button in the popup to get an AI translation
• Deck selector — choose which deck to save words to from the popup

The extension works with all plans. Log in with your Words on Repeat account through the extension popup. Recently saved words are tracked in the popup for quick reference.

REST API Reference

Words on Repeat exposes 30+ REST endpoints for programmatic access. You can use these from scripts, AI assistants, or external tools.

Authentication

All endpoints (except login and /api/spec) require authentication. Two methods are supported:

• JWT cookie — automatic in the browser after login.
• API key header — Authorization: Bearer sk_your_key_here. Generate keys in Settings.

Endpoints marked JWT only require browser login — API keys are not accepted for destructive operations (deck delete, password change) or study/progress endpoints.

API Spec (Machine-Readable)

Fetch /api/spec (no auth required) to get a compact JSON description of every endpoint, including auth requirements, request bodies, query parameters, and response shapes. This is designed for LLMs and AI tools to discover the API programmatically.

Endpoints

Auth

Admin

All admin endpoints require JWT with the admin role.

Roles: Users can have multiple roles stored as an array: admin, user, api_user. The admin role grants access to user management. The api_user role (or admin) allows creating API keys.

Decks

Deck Sharing

Vocabulary

All list/create operations require deck_id parameter.

Study

Progress

Import / Export

API Keys

Error Responses

All errors return JSON with an error field, e.g. { "error": "deck_id is required" }

Vocabulary Generation

The easiest way to generate vocabulary is using the built-in AI Extract feature. Paste text, enter a URL, upload a file, or use a YouTube video — the AI extracts vocabulary automatically and adds it to your deck.

For advanced users, you can also import words via the REST API. See the API Endpoints section for POST /api/vocabulary/batch.

Keyboard Shortcuts