Gordito

Save words the learner wants to remember. Each item pairs the word in their own language with the word in the language they are learning — check get_enrollments for which is which before you write them, and never put the same language in both fields. A pair like originWord "la mesa" / learningWord "la mesa" is a broken row: the learner will be asked to translate a word into itself. Include an example sentence in the learned language whenever you can: it is what makes the word reviewable later. New words are due immediately.

add_vocabulary

Called by the language picker when the learner presses start. Opens their notebook for the pair they chose. Asking again for a pair they already have returns that same enrollment rather than a second one.

create_enrollment

List the signed-in learner's language enrollments. Each enrollment pairs an origin language with a language being learned, and owns that learner's vocabulary, quizzes and error history. Call this first: every other tool needs an enrollmentId. If the learner has none, call get_enrollment_creator, which puts a picker on screen for them to choose their languages themselves.

get_enrollments

Read back what the learner answered, with the vocabulary each question was testing. Call this when you need the answers to grade and they were not handed to you — the learner may have answered on their phone at the quiz link rather than in the card. Use learningWord to judge whether the response was right. Scores, the correction note and errors come back empty or null for anything you have not graded yet.

get_results

List what the learner has saved, soonest due first. Pass dueOnly to get exactly the words the spaced-repetition schedule says are due right now — that set is the entire pool you may quiz, and scheduling is decided by the server using FSRS, so never guess what is due or when a word should come back. Leave dueOnly off to browse the whole notebook: to look something up, to check what is already stored before adding a duplicate, or to find rows that were saved wrong — a pair with the same language on both sides, say — so you can repair them with update_vocabulary. Pass search only when the learner asks about one specific word.

get_vocabulary

Grade the answered questions of a quiz and advance the spaced-repetition schedule. Send every question you are marking in one call: the batch is written together or not at all, so a quiz is never left half-marked. Score every word a question tested, separately: the same sentence can be right on one and wrong on another, and each word's schedule moves on its own evidence. The score is the FSRS rating: 1 Again (wrong or blank), 2 Hard (right but laboured), 3 Good (right), 4 Easy (immediate and idiomatic). Any score of 1 must record at least one error — you cannot mark something wrong without saying what was wrong. A question the learner left blank is graded 1, never skipped. Be honest: a generous grade tells the scheduler the learner knows a word they do not, and they will stop seeing it. Write correctionNote and every error rule in the language being learned — the enrollment's learningLanguage, the same language the learner is producing. Reading the explanation is itself practice; do not fall back to English.

grade_questions

Present a quiz to the learner and collect their answers. Build the questions from get_vocabulary with dueOnly set — every question must name the vocabularyIds it tests, or the review will not count. A question may test more than one word, and each is graded on its own afterwards. The learner answers either in the card on screen or on their phone at the returned link. Answering in the card sends you the answers directly; if they used the link instead, call get_results with the quizId to read them back. Either way, grade the whole quiz with a single grade_questions call. The questions are handed to the card, not to you — never ask the learner to retype what they already typed.

generate_quiz

Put a picker on screen so the learner can choose the languages of a new notebook themselves. Call it when they ask to set up or add a language pair, and when get_enrollments comes back empty — a learner with no enrollment cannot save a word or sit a quiz until one exists. Do not choose the languages yourself: the card collects them, creates the notebook, and tells you when it is done. The response also carries a browser link for a client that cannot render the card.

get_enrollment_creator

Called by the quiz card when the learner submits. Records what they wrote against each question. An empty response is allowed and means the question was left blank.

submit_answers

Correct words that were saved wrong, one or many at a time. Send only the fields you are changing; anything you leave out keeps its current value. Review history is untouched, so fixing a typo does not reset the learner's schedule. Get the vocabularyId values from get_vocabulary.

update_vocabulary