Chamelingo API Documentation

How FSRS-5 works in the API — review workflow, rating scale, and deck management.

Chamelingo uses FSRS-5 (Free Spaced Repetition Scheduler, version 5), a modern algorithm that outperforms SM-2 (Anki's default). The API exposes the full FSRS workflow.

Card States#

Each card has a card_state representing where it is in the learning cycle:

State	Value	Meaning
`new`	0	Never reviewed — waiting for first study
`learning`	1	In initial learning phase
`review`	2	Graduated to long-term review
`relearning`	3	Failed a review — back in short-term study

Rating Scale#

When submitting reviews, use these ratings:

Rating	Label	When to use
1	Again	Complete blackout — didn't remember at all
2	Hard	Remembered with significant effort
3	Good	Remembered with moderate effort
4	Easy	Instant recall — no effort needed

Review Workflow#

1. Get Due Cards#

bash

curl "https://api.chamelingo.com/api/v1/decks/DECK_ID/cards/review?limit=20" \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE"

Cards are returned sorted by due date (most overdue first).

2. Present to User and Collect Ratings#

Show the front of each card, let the user attempt recall, reveal the back, and collect their self-assessment (1-4).

3. Submit Batch Results#

bash

curl -X POST https://api.chamelingo.com/api/v1/reviews \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "results": [
      {"card_id": "card_abc", "rating": 3},
      {"card_id": "card_def", "rating": 1}
    ]
  }'

FSRS-5 automatically calculates the next review date based on the rating, current stability, and difficulty.

Filtering Cards by State#

Get only cards in a specific state:

bash

# New cards only
curl "https://api.chamelingo.com/api/v1/decks/DECK_ID?card_state=new" \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE"

# Cards due before tomorrow
curl "https://api.chamelingo.com/api/v1/decks/DECK_ID?due_before=2026-03-21T00:00:00Z" \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE"

Identifying Difficult Words#

Use the progress API to find words the user struggles with:

bash

curl "https://api.chamelingo.com/api/v1/progress/vocabulary/difficult?sort_by=FAILURE_RATE" \
  -H "Authorization: Bearer ck_live_YOUR_KEY_HERE"

Tip

Combine difficult words data with the AI tutor — ask the tutor to create example sentences for words with high failure rates.