Vocabulary and reviews with the API

Both endpoints here need a key with the vocabulary:read scope. They are read-only: nothing on this page changes your vocabulary or your review schedule.

If you created your API key before these endpoints existed, it does not have the new scope. Create a new key to use them - an existing key cannot have scopes added to it.

Look a word up

curl "https://yalango.com/api/v1/vocabulary?language=es&word=el%20perro" \
  -H "Authorization: Bearer yal_your_key_here"

{
  "language": "es",
  "word": "el perro",
  "items": [
    {
      "item_id": "Vx8QmRt2YsKdLp4n",
      "source": "the dog",
      "target": "el perro",
      "status": "active",
      "spaced_repetition_level": 4,
      "next_review": "2026-04-02T03:00:00.000Z",
      "deck_doc_ids": ["8sKd92mfPqR1xLvBn4Tz"]
    }
  ]
}

An empty items array means you are not studying that word yet. That is what makes this useful before a write: check first, and you avoid ending up with the same word in three decks.

deck_doc_ids lists every deck the word appears in, because vocabulary is shared across all your decks and tables rather than owned by one of them.

Matching is exact

word is matched against both source and target, exactly, ignoring case. There is no prefix, partial or fuzzy matching - searching for perro will not find el perro. Both language and word are required, and language is the target language of the vocabulary you want to search.

Statuses

Status	Meaning
active	Being studied normally. Most words.
paused	Taken out of rotation by you. Not served by a study session.
learnt	Marked as known. Not served by a study session.
deleted	Removed from your vocabulary.

spaced_repetition_level is the word's position on the review ladder, and next_review is null for a word you have never reviewed.

See what is due for review

curl "https://yalango.com/api/v1/review?language=es" \
  -H "Authorization: Bearer yal_your_key_here"

{
  "languages": ["es"],
  "overdue": 7,
  "due_today": 12,
  "unstarted": 40,
  "forecast": [
    { "date": "2026-04-03", "due": 5 },
    { "date": "2026-04-04", "due": 18 }
  ],
  "timezone_offset": -120
}

Field	What it counts
overdue	Scheduled before today and still not reviewed.
due_today	Scheduled for today.
unstarted	Never reviewed - new material a session can draw on.
forecast	The days after today, oldest first.

Leave language out to total every language you study. languages in the response always tells you which ones the numbers cover.

The first three numbers match what a session serves

overdue, due_today and unstarted exclude words you have paused, marked as learnt, or deleted - exactly as a real study session does. So overdue + due_today is the number of reviews actually waiting for you, not a count of rows in a table.

forecast is a projection of the stored schedule and does not apply that filter, so a day further out may read slightly high. It is a forecast either way: a word you pause tomorrow will not be due next week regardless of what today's number says.

Days and timezones

A Yalango study day starts at 04:00 in your local time, not at midnight, so a late-night session still counts toward the right day. The dates in forecast are study days in your timezone.

The API uses the timezone saved in your account, which the web app keeps up to date. If you need a different one for a single request, pass timezone_offset in minutes, following JavaScript's getTimezoneOffset - so UTC+2 is -120:

curl "https://yalango.com/api/v1/review?language=es&timezone_offset=-120" \
  -H "Authorization: Bearer yal_your_key_here"

This applies to that request only. It never overwrites the timezone your account uses everywhere else.

You cannot review through the API

There is no endpoint for answering a card or advancing the schedule. Reviews have to happen in a game in the app, where the answer and the time taken are recorded together. These endpoints tell you what is waiting; the studying still happens in Yalango.