Skip to the page
Lymidocs

API

Quickstart

By the end of this page you will have a key, a deck id, and a card that you added from the command line and can see in the app.

  1. Make a key

    Open Settings in Lymi, find API keys, name the key after the thing that will use it, and choose Read and write.

    The key is shown once, right after you make it. Copy it now; the server keeps only a hash. Every key starts with lymi_.

    Terminal
    export LYMI_KEY=lymi_your_key_here
export LYMI_URL=https://my.lymi.app

  2. Check that it works

    Ask the API who the key belongs to.

    curl "$LYMI_URL/api/me" -H "x-api-key: $LYMI_KEY"

    You get the learner the key belongs to:

    Response
    {
  "id": "0mtoyiymrpxx21q8gp6",
  "name": "Kateryna",
  "email": "you@example.com"
}

    A 401 here means the key is wrong or revoked. Nothing else can cause it.

  3. Find a deck to add to

    Every card belongs to a deck, so you need a deck id first. This lists the decks you have, with how many cards are in each and how many are due right now.

    Terminal
    curl "$LYMI_URL/api/decks" -H "x-api-key: $LYMI_KEY"
    Response
    [
  {
    "id": "0mtoyiymqa34h1xeaqo",
    "name": "Italian",
    "description": null,
    "defaultLanguage": "it",
    "directions": "both",
    "position": 0,
    "total": 214,
    "due": 12
  }
]

    No decks yet? Make one with POST /api/decks. A name is the only field it needs.

  4. Add a card

    The deck id and the term are required. Everything else is optional, and anything you leave out stays empty until you fill it in the app.

    curl "$LYMI_URL/api/cards" \
  -H "x-api-key: $LYMI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "deckId": "0mtoyiymqa34h1xeaqo",
    "term": "la nebbia",
    "meaning": "fog",
    "example": "La nebbia copre la valle ogni mattina.",
    "language": "it",
    "tags": ["weather"]
  }'

  5. Read the outcome

    You get 201 with status: "added" and the whole card. If that term is already in one of your decks you get 200 with status: "skipped" and the card that already holds it. Adding the same term twice is never an error.

    Response · 201
    {
  "status": "added",
  "card": {
    "id": "0mtoyiymrvqpdz02hlv",
    "deckId": "0mtoyiymqa34h1xeaqo",
    "term": "la nebbia",
    "normalizedTerm": "la nebbia",
    "meaning": "fog",
    "language": "it",
    "tags": ["weather"],
    "createdBy": "api",
    "archivedAt": null,
    "createdAt": "2026-09-06T08:14:22.000Z"
  }
}

  6. Open Lymi

    The card is in the deck already, marked New, and it joins the queue at your next review. Nothing is held for approval.

Adding a whole lesson

One lesson is twenty to forty cards. Send them together rather than one call per card: POST /api/cards/batch takes up to 200 cards, across any decks, and returns one outcome per card in the order you sent them.

Terminal
curl "$LYMI_URL/api/cards/batch" \
  -H "x-api-key: $LYMI_KEY" \
  -H "content-type: application/json" \
  -d '{"cards": [
    { "deckId": "0mtoyiymqa34h1xeaqo", "term": "la nebbia", "meaning": "fog" },
    { "deckId": "0mtoyiymqa34h1xeaqo", "term": "il tramonto", "meaning": "sunset" }
  ]}'

Where to go next