Lingoborn API v1

Create an account and receive a token.

curl -X POST https://api.lingoborn.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret6","name":"Vlad"}'

{ "token": "eyJhbGciOi…", "user": { "id": 1, "email": "you@example.com", "name": "Vlad" } }

Verify credentials and receive a 7-day token. This is where you get the token for every other call.

curl -X POST https://api.lingoborn.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret6"}'

{ "token": "eyJhbGciOi…", "user": { "id": 1, "email": "you@example.com", "name": "Vlad" } }

The current user's profile.

curl https://api.lingoborn.com/me -H "Authorization: Bearer $TOKEN"

{ "user": { "id": 1, "email": "you@example.com", "name": "Vlad",
  "country": "", "learningGoal": "", "level": "", "dailyGoal": 0,
  "interests": [], "knownLanguages": [] } }

Update editable profile fields. Send only what you want to change. email and password cannot be changed here.

curl -X PUT https://api.lingoborn.com/me \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"level":"B1","dailyGoal":10}'

{ "user": { "id": 1, "level": "B1", "dailyGoal": 10, … } }

Permanently delete the account and all its data (words, stories, groupings, stats cascade).

{ "ok": true }

List words with filtering, sorting and cursor pagination.

curl "https://api.lingoborn.com/v1/words?fields=compact&limit=5&sort=alpha&state=to_learn" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    { "id": 12, "uuid": "…", "english": "apple", "russian": "яблоко",
      "category": "Food", "state": "to_learn", "partOfSpeech": "",
      "type": "word", "createdAt": "2026-09-01T…", "updatedAt": "2026-09-01T…" }
  ],
  "nextCursor": "12"
}

Aggregate counts only — answers "how many words / per stage / per category / per part of speech" without returning any rows.

curl https://api.lingoborn.com/v1/words/summary -H "Authorization: Bearer $TOKEN"

{
  "total": 42,
  "byState": { "to_learn": 20, "practiced": 15, "learned": 7 },
  "byCategory": [ { "category": "Food", "count": 12 }, { "category": "Travel", "count": 8 } ],
  "byPartOfSpeech": { "unknown": 42 }
}

One word by numeric id — always the full card. 404 if not found.

curl https://api.lingoborn.com/v1/words/12 -H "Authorization: Bearer $TOKEN"

{ "id": 12, "english": "apple", "russian": "яблоко", "category": "Food",
  "state": "to_learn", "type": "word", "pronunciation": "/ˈæp.əl/",
  "synonyms": [], "architecture": { "type": "word", … }, "examples": [ … ] }

All categories (derived from your words' groups), each with a word count and whether it has a synonym/antonym grouping and stories.

curl https://api.lingoborn.com/v1/categories -H "Authorization: Bearer $TOKEN"

{ "categories": [
  { "category": "Food", "wordCount": 12, "hasGrouping": true, "storyCount": 2 }
] }

The synonym/antonym clusters for a category. URL-encode names with spaces (Phrasal%20Verbs). 404 if the category has no grouping.

curl "https://api.lingoborn.com/v1/categories/Food/grouping" -H "Authorization: Bearer $TOKEN"

{ "category": "Food", "clusters": [ … ], "updatedAt": "2026-09-…" }

List stories, newest first. Optional ?category= filter.

curl "https://api.lingoborn.com/v1/stories?category=Food" -H "Authorization: Bearer $TOKEN"

{ "items": [
  { "id": 3, "uuid": "…", "category": "Food", "title": "Breakfast",
    "story": "…", "wordsUsed": ["apple","bread"], "createdAt": "…", "updatedAt": "…" }
] }

One story by numeric id. 404 if not found.

curl https://api.lingoborn.com/v1/stories/3 -H "Authorization: Bearer $TOKEN"

{ "id": 3, "category": "Food", "title": "Breakfast", "story": "…", "wordsUsed": [ … ] }

Daily learning stats plus totals over the range.

curl "https://api.lingoborn.com/v1/stats?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TOKEN"

{
  "days": [ { "date": "2026-09-10", "added": 3, "checked": 5,
            "toLearn": 1, "practiced": 2, "learned": 2 } ],
  "totals": { "added": 3, "checked": 5, "toLearn": 1, "practiced": 2, "learned": 2 }
}