Lingoborn API Reference

The complete backend API for the mobile app, web app, AI features, LiveChat and learning-data synchronization.

Overview

All requests are HTTPS and return JSON. Send and receive UTF-8. The base URL is:

# Base URL
https://api.lingoborn.com

The mobile and web applications call this backend. The backend's /ai/* routes call Infobip AI Components server-side; clients do not call Infobip AI directly and must never contain provider secrets.

How the pieces fit together

Mobile/Web application → authenticated Lingoborn backend API
Backend /ai/* routes → Infobip AI Components
LiveChat client → POST /livechat/token, then Infobip LiveChat
Mobile synchronization → POST /sync
AgentOS tutor → /agent/* tools (machine-to-machine secret + learner email; never a user JWT)
AudienceUse these routesAuthentication
Health checksGET /healthNone
Mobile and web users/auth/*, /me, /v1/*User JWT
Signed-in AI features/ai/*User JWT
LiveChat setupPOST /livechat/tokenUser JWT
Mobile offline syncPOST /syncUser JWT
AgentOS tutor (server-to-server)/agent/*Agent secret + X-User-Email

Authentication

The API uses Bearer token (JWT) authentication. Obtain a token from POST /auth/login (or /auth/register); it is valid for 7 days. Send it on every protected request:

Authorization: Bearer <your-token>

A caller only ever sees its own account's data. Requests without a valid token get 401.

In Postman: run POST /auth/login, copy token from the response, then set the collection Authorization → Bearer Token to that value and have each request inherit auth from parent. Or auto-capture it with a Login Test script: pm.collectionVariables.set("token", pm.response.json().token).

Conventions

TopicDetail
Content typeRequest bodies are application/json. Set Content-Type: application/json on POST/PUT.
PaginationGET /v1/words is cursor-based: pass limit (≤ 200) and the previous nextCursor as cursor. nextCursor: null means the last page. Other list endpoints return their complete scoped list.
Projectionfields=compact (default) returns a light record; fields=full returns the whole card.
DeletesDeleted rows are hidden everywhere (soft-deleted); reads mirror exactly what the app shows.
TimestampsISO-8601 UTC (e.g. 2026-09-11T09:13:00.000Z).

Errors

Standard HTTP status codes; the body is always { "error": "…" }.

StatusMeaning
400Invalid input or a non-numeric :id.
401Missing, invalid, or expired bearer token — log in again.
404Resource not found (or not yours).
409Conflict (e.g. registering an email that already exists).
429Too many requests (/agent/*: more than 60 per minute per learner). See the Retry-After header.
500Server error.
502Upstream AI request failed.
503Feature not configured on the server (/agent/* without an agent secret).

System

GET/healthNo auth

Lightweight liveness check for the backend process.

Request
curl https://api.lingoborn.com/health
Response 200
{ "ok": true, "service": "lingoborn-backend" }

Auth

POST/auth/registerNo auth

Create an account and receive a token.

Body
FieldType
emailstringrequired
passwordstring (min 6)required
namestringrequired
country, gender, learningGoal, levelstringoptional
knownLanguages, interestsstring[]optional
dailyGoalintegeroptional
remindersbooleanoptional
Request
curl -X POST https://api.lingoborn.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret6","name":"Vlad"}'
Response 201
{ "token": "eyJhbGciOi…", "user": { "id": 1, "email": "you@example.com", "name": "Vlad" } }
POST/auth/loginNo auth

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

Body
FieldType
emailstringrequired
passwordstringrequired
Request
curl -X POST https://api.lingoborn.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret6"}'
Response 200
{ "token": "eyJhbGciOi…", "user": { "id": 1, "email": "you@example.com", "name": "Vlad" } }
Invalid credentials return 401 { "error": "Invalid email or password." }.

Profile

GET/meBearer

The current user's profile.

Request
curl https://api.lingoborn.com/me -H "Authorization: Bearer $TOKEN"
Response 200
{ "user": { "id": 1, "email": "you@example.com", "name": "Vlad",
  "country": "", "learningGoal": "", "level": "", "dailyGoal": 0,
  "interests": [], "knownLanguages": [] } }
PUT/meBearer

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

Body (all optional)
FieldType
name, country, gender, learningGoal, levelstring
knownLanguages, interestsstring[]
dailyGoalinteger
remindersboolean
Request
curl -X PUT https://api.lingoborn.com/me \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"level":"B1","dailyGoal":10}'
Response 200
{ "user": { "id": 1, "level": "B1", "dailyGoal": 10, … } }
PUT/me/avatarBearer

Set the profile photo. Resize it first: the apps crop it square and save it as a 512 × 512 JPEG (about 100 KB). DELETE /me/avatar removes it. Every profile response has avatarUrl: a path on this host (/avatars/<id>-<token>.jpg, no auth needed, changes on every upload) or null.

Body
FieldType
imagebase64 string or data:image/…;base64, URL. JPEG, PNG or WebP, max 2 MB.
Request
curl -X PUT https://api.lingoborn.com/me/avatar \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"image\":\"$(base64 -i avatar.jpg)\"}"
Response 200
{ "user": { "id": 1, "avatarUrl": "/avatars/1-3f9c0a7d2b1e4c5f6a7b8c9d.jpg", … } }
The type is checked from the file bytes, not the declared type. 415 for anything else (GIF, SVG, HEIC: convert HEIC to JPEG before upload), 413 over 2 MB, 400 if image is missing or not base64.
DELETE/meBearer

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

Response 200
{ "ok": true }

AI generation

These routes are for signed-in app users. They authenticate with the same user JWT as /v1. The backend forwards the request to Infobip AI Components and returns the component output; keep all provider credentials on the backend.

POST/ai/wordBearer

Enrich one word or phrase with an AI vocabulary card. The input is limited to 100 characters; a phrase is kept and taught as a whole (never reduced to one of its words).

Body
{ "word": "resilient", "context": "(optional) The sentence it came from. Meaning: …" }
Response 200
{ "output": { … } }
context (optional, ≤500 characters): the sentence the word came from plus the meaning to use; the card is then in that sense.
POST/ai/sentenceBearer

Translate 1–3 sentences (up to 300 characters) and suggest words and phrases worth learning from them. Used by Add word when the learner types a sentence. kind: "phrase" means the whole text is a fixed expression (proverb, idiom): make one card with /ai/word instead. To save a suggestion, call /ai/word with context = its sentence + meaning, and store the sentence as the card's example.

Body
{ "text": "We need to account for every endpoint." }
Response 200
{ "kind": "sentence",
  "sentences": [ { "en": "We need to account for every endpoint.", "ru": "Нам нужно учесть каждый эндпоинт." } ],
  "items": [ { "english": "account for", "russian": "учитывать", "kind": "phrase", "sentenceIndex": 0 } ] }
At most 6 items. sentenceIndex points into sentences. 400 for empty or over-long text, 502 if the AI fails.
POST/ai/storyBearer

Generate a learning story using a category and a list of words.

Body
{ "category": "Food", "words": ["apple", "bread"] }
Response 200
{ "output": { … } }
POST/ai/fillerBearer

Generate a synchronous batch of new words for a category. The backend returns the raw AI component output; persist accepted cards through the write API.

Body
FieldType
categorystringrequired
countpositive integerrequired
existingWordsstring[]required
Response 200
{ "output": { … } }
POST/ai/grouperBearer

Group words in a category into synonym/antonym or learning clusters.

Body
{ "category": "Travel", "words": ["journey", "trip"] }
Response 200
{ "output": { … } }
POST/ai/filler-jobBearer

Start a background filler job for a larger batch. The request returns immediately with 202; the server generates and persists new words in batches.

Body
FieldType
categorystringrequired
targetpositive integer, max 50required
existingWordsstring[]optional, defaults to []
Response 202
{ "job": { "id": "…", "kind": "filler", "category": "Travel", "target": 20, "added": 0, "status": "running", "error": null } }
If a filler job is already running for the same user and category, this endpoint returns that existing job instead of creating a second one.
GET/ai/jobsBearer

Find the latest background generation job for the signed-in user.

Query parameters (optional)
ParamPurpose
categorymatch one category
statusmatch a status such as running, completed or failed
Response 200
{ "job": { … } } // or { "job": null }
GET/ai/jobs/:idBearer

Read one generation job. Jobs are scoped to the authenticated user; another user's job returns 404.

Response 200
{ "job": { "id": "…", "kind": "filler", "category": "Travel", "target": 20, "added": 14, "status": "completed", "error": null } }

Integrations

POST/livechat/tokenBearer

Mint a short-lived, user-specific LiveChat personalization token. The backend signs it with the server-side LiveChat configuration; the app only receives the token it needs to initialize the user's LiveChat session.

Response 200
{ "jwt": "eyJhbGciOi…", "sid": "…", "widgetId": "…", "sessionTimeoutMinutes": 1440 }

sessionTimeoutMinutes is how long the AI tutor remembers a conversation without messages (1–1440, default 1440 = 24 hours). After that, the tutor starts over, so clients start a new conversation instead of continuing the old one.

Do not put the LiveChat widget secret or any backend environment secret in mobile, web, or documentation code. The client uses the returned jwt with LiveChat's mobile session API.
POST/syncBearer

Push local mobile changes, then pull rows changed since the last server cursor. The endpoint is authenticated and user-scoped.

Body
{
  "since": "2026-09-11T09:13:00.000Z",
  "changes": {
    "words": [ { "uuid": "…", "english": "apple", "russian": "яблоко", "deleted": false } ],
    "decks": [ { "uuid": "…", "name": "Doctor visit", "deleted": false } ],
    "stories": [], "groupings": [], "dailyStats": []
  }
}
Response 200
{ "serverTime": "2026-09-11T09:14:00.000Z", "changes": { "words": [ … ], "decks": [ … ], "stories": [ … ], "groupings": [ … ], "dailyStats": [ … ] } }
Store the returned serverTime and send it as since on the next sync. Deletes are represented as tombstones; pushed rows are omitted from the same response to avoid an immediate echo.

Words

GET/v1/wordsBearer

List words with filtering, sorting and cursor pagination.

Query parameters (all optional)
ParamValuesDefault
fieldscompact · fullcompact
limit1–20050
cursorthe nextCursor from a prior page—
sortcreated · alpha · updatedcreated
categoryexact group name, e.g. Food—
stateto_learn · practiced · learned—
qsearch in english/russian (case-insensitive)—
partOfSpeechexact, e.g. verb (empty until enriched)—
createdAfter / createdBeforedate, e.g. 2026-01-01—
Request
curl "https://api.lingoborn.com/v1/words?fields=compact&limit=5&sort=alpha&state=to_learn" \
  -H "Authorization: Bearer $TOKEN"
Response 200 — compact items
{
  "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"
}
fields=full adds: pronunciation, example, exampleRu, imageEmoji, explanationEn, explanationRu, synonyms[], architecture{}, examples[], audioUrl, lastPracticedAt, practiceCount, correctCount, srsEase, srsIntervalMin, srsHistory[]. Every item (compact too) has srsRepetition and srsDueAt (spaced repetition; null = never reviewed). due=1 returns the practice deck: words due for review now (most overdue first) and never-reviewed words.
GET/v1/words/summaryBearer

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

Request
curl https://api.lingoborn.com/v1/words/summary -H "Authorization: Bearer $TOKEN"
Response 200
{
  "total": 42,
  "byState": { "to_learn": 20, "practiced": 15, "learned": 7 },
  "byCategory": [ { "category": "Food", "count": 12 }, { "category": "Travel", "count": 8 } ],
  "byPartOfSpeech": { "unknown": 42 }
}
GET/v1/words/:idBearer

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

Request
curl https://api.lingoborn.com/v1/words/12 -H "Authorization: Bearer $TOKEN"
Response 200 (abridged)
{ "id": 12, "english": "apple", "russian": "яблоко", "category": "Food",
  "state": "to_learn", "type": "word", "pronunciation": "/ˈæp.əl/",
  "synonyms": [], "architecture": { "type": "word", … }, "examples": [ … ] }
POST/v1/wordsBearer

Create one vocabulary card. By default, an existing non-deleted word with the same English spelling (case-insensitive) is returned instead of creating a duplicate.

Body
FieldType
english, russianstringrequired
category, state, partOfSpeechstringoptional
pronunciation, example, exampleRu, imageEmoji, explanationEn, explanationRu, audioUrlstringoptional
synonyms, examples, architecturearray/objectoptional
forcebooleanoptional; create even if a duplicate exists
Request
curl -X POST https://api.lingoborn.com/v1/words \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"english":"resilient","russian":"стойкий","category":"Work"}'
Response 201
{ "id": 43, "english": "resilient", "russian": "стойкий", … }
A duplicate response is 200 and includes duplicate: true. New cards start in to_learn unless another valid state is supplied.
PATCH/v1/words/:idBearer

Update any supplied word-card fields, or reset practice progress with { "reset": true }.

Request
curl -X PATCH https://api.lingoborn.com/v1/words/43 \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"category":"Work","state":"practiced"}'
Response 200
{ "id": 43, "category": "Work", "state": "practiced", … }
DELETE/v1/words/:idBearer

Soft-delete one word. It disappears from normal reads and is retained as a sync tombstone.

Response 200
{ "ok": true }
POST/v1/words/bulkBearer

Bulk-create cards or apply a category/state change to selected words.

Body — one operation per request
// Create cards
{ "create": [ { "english": "calm", "russian": "спокойный" } ] }

// Update by ids or filter
{ "ids": [43, 44], "set": { "category": "Work" } }
{ "filter": { "state": "to_learn" }, "set": { "state": "practiced" } }
Response 200
{ "created": 1 } // create operation
{ "updated": 2 } // set operation

Decks & categories

POST/v1/decksBearer

Create a persistent, initially empty deck. Words added to it use the same name as their category. A case-insensitive name already used by a deck or word category returns 409.

Body
FieldType
namestring, trimmed, 1–80 charactersrequired
Request
curl -X POST https://api.lingoborn.com/v1/decks \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Doctor visit"}'
Response 201
{ "deck": { "id": 7, "uuid": "…", "name": "Doctor visit", "createdAt": "…", "updatedAt": "…" } }
Returns 400 for an empty or overlong name and 409 when that name is already used by a deck or category.
GET/v1/categoriesBearer

List word categories and persistent decks, including empty decks, with word counts and whether each has a synonym/antonym grouping and stories. Existing words remain grouped by their groupName.

Request
curl https://api.lingoborn.com/v1/categories -H "Authorization: Bearer $TOKEN"
Response 200
{ "categories": [
  { "category": "Food", "wordCount": 12, "hasGrouping": true, "storyCount": 2 },
  { "category": "Doctor visit", "wordCount": 0, "hasGrouping": false, "storyCount": 0 }
] }
GET/v1/categories/:name/groupingBearer

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

Request
curl "https://api.lingoborn.com/v1/categories/Food/grouping" -H "Authorization: Bearer $TOKEN"
Response 200
{ "category": "Food", "clusters": [ … ], "updatedAt": "2026-09-…" }
PATCH/v1/categories/:nameBearer

Rename a category across the authenticated user's words, stories, grouping and matching persistent deck records when possible.

Body
{ "newName": "Healthy Food" }
Response 200
{ "from": "Food", "to": "Healthy Food", "renamedWords": 12, "renamedStories": 2, "renamedDecks": 1 }
POST/v1/categories/:name/groupingBearer

Create or replace the synonym/antonym clusters for a category.

Body
{ "clusters": [ { "label": "Movement", "words": ["walk", "stroll"] } ] }
Response 200
{ "category": "Travel", "clusters": [ … ], "updatedAt": "2026-09-…" }

Stories

GET/v1/storiesBearer

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

Request
curl "https://api.lingoborn.com/v1/stories?category=Food" -H "Authorization: Bearer $TOKEN"
Response 200
{ "items": [
  { "id": 3, "uuid": "…", "category": "Food", "title": "Breakfast",
    "story": "…", "wordsUsed": ["apple","bread"], "createdAt": "…", "updatedAt": "…" }
] }
GET/v1/stories/:idBearer

One story by numeric id. 404 if not found.

Request
curl https://api.lingoborn.com/v1/stories/3 -H "Authorization: Bearer $TOKEN"
Response 200
{ "id": 3, "category": "Food", "title": "Breakfast", "story": "…", "wordsUsed": [ … ] }
POST/v1/storiesBearer

Persist a story that was generated through /ai/story or supplied by another trusted client.

Body
FieldType
category, storystringrequired
titlestringoptional
wordsUsedstring[]optional
Request
curl -X POST https://api.lingoborn.com/v1/stories \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"category":"Food","title":"Breakfast","story":"…","wordsUsed":["apple"]}'
Response 201
{ "id": 3, "uuid": "…", "category": "Food", "title": "Breakfast", … }
DELETE/v1/stories/:idBearer

Soft-delete one story. It is hidden from normal reads and retained for synchronization.

Response 200
{ "ok": true }

Practice

POST/v1/practiceBearer

Record one practice result and advance the word state. A correct answer moves to_learn → practiced → learned; an incorrect answer moves the word back to to_learn. It also updates the word's spaced-repetition schedule: srsRepetition, srsEase, srsIntervalMin, srsDueAt (next review) and srsHistory (a 4-day plan of 5 / 3 / 2 / 1 reviews, then growing gaps; a mistake reschedules the word in 15 minutes). For writing practice send { "wordId", "mode": "tiles" | "type", "answer", "ms" } instead of correct: the server grades the answer (small typos and synonyms accepted) and adds grade (q, verdict, expected) and extra to the response. A good typed answer moves the schedule further than a card.

Body
{ "wordId": 43, "correct": true }
Response 200
{ "id": 43, "state": "learned", "practiceCount": 3, "correctCount": 3, "srsRepetition": 3, "srsDueAt": "2026-11-02T11:15:00.000Z", … }

Grammar

Grammar topics and exercises are user-scoped. When grammar generation is configured, a confirmed topic queues server-side sentence generation from vetted grammar seeds and the learner's active saved vocabulary. Ready generated items are preferred, with deterministic vocabulary recipes and fixed banks as the pending/failed fallback. The backend keeps answer keys and vocabulary provenance private; session responses remain answer-free.

GET/v1/grammar/topicsBearer

List the learner's in-progress and completed grammar topics, their progress, rules, examples, and recent mistakes. Every confirmed topic is immediately available for practice; there is no active-topic cap.

Response 200
{ "topics": [ { "topicKey": "articles", "status": "learning", "streak": 2, "due": true, … } ], "dueCount": 1 }
GET/v1/grammar/session?topic=Bearer

Without a topic, build a mixed session for topics due now. With a selected topic, practice it any day, regardless of its suggested next date. When generation is configured, ready vocabulary-rich generated items are preferred; deterministic personalized recipes and fixed-bank items remain available while generation is pending or failed. Generation targets at least 90% saved-vocabulary coverage among compatible items. Answers and provenance are never returned. Treat each item id as opaque and submit it unchanged.

Query parameter (optional)
ParamPurpose
topicOne learning or completed topic key to practice now, even when it is not due; omit to mix topics due now.
Response 200
{ "items": [ { "id": "…", "topicKey": "articles", "kind": "choose", "text": "I saw ___ doctor this morning.", "options": ["a", "an", "the", "—"] } ] }
POST/v1/grammar/answerBearer

Submit an answer for server-side grading and update topic progress. Check-ups for completed topics are tracked by the server.

Body
{ "itemId": "…", "answer": "a", "topicKey": "articles" }
Errors

400 for invalid input; 404 when the item or topic is unavailable.

PATCH/v1/grammar/topics/:keyBearer

Turn one topic off or turn it back on.

Body
{ "status": "off" }
Response 200
{ "topicKey": "articles", "status": "off" }
POST/v1/grammar/mistakes/:id/dismissBearer

Dismiss a logged mistake so it no longer contributes to topic offers or relapse handling.

Response 200
{ "ok": true }

Stats

GET/v1/statsBearer

Daily learning stats plus totals over the range.

Query parameters (optional)
ParamFormat
fromYYYY-MM-DD
toYYYY-MM-DD
Request
curl "https://api.lingoborn.com/v1/stats?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TOKEN"
Response 200
{
  "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 }
}

AgentOS tutor tools

Server-to-server tools for the Lingoborn AI chat tutor running in Infobip AgentOS. The tutor explains a word, asks the learner to confirm, then saves it to that learner's dictionary. These routes are not for mobile or web clients and never accept a user JWT.

Authentication — every request
Authorization: Bearer <AGENT_API_SECRET>   # shared service secret, ≥ 32 chars, server-side only
X-User-Email: learner@example.com           # the learner to act for (case-insensitive)
Content-Type: application/json              # POST only
RuleDetail
Learner scopeEvery read and write is limited to the learner resolved from X-User-Email.
Identity sourceThe email must come from the signed-in LiveChat personalization (CDP), never from text the learner typed in chat.
Rate limit60 requests per minute per learner → 429 with Retry-After.
SyncSaved words use the same sync format as app-added words and reach the mobile app on its next POST /sync. The server only sees words the app has already synced.
Word object{ id, english, russian, category, state }, where state is to_learn · practiced · learned.
StatusWhen
401Missing or wrong agent secret (including a user JWT sent instead).
400Missing or invalid X-User-Email (usually an empty chatbot attribute), or invalid input.
404No Lingoborn account for that email.
429Rate limit exceeded.
502AI word lookup failed; nothing was saved.
503AGENT_API_SECRET is not configured on the server.
Anyone with the agent secret can act for any learner. Keep it only in the backend environment and the AgentOS tool configuration. Never put it in a browser, mobile app, repository or documentation.
POST/agent/vocab/resolveAgent secret

Look up a word through the Vocabulary Tutor AI (same component as POST /ai/word) and report whether the learner already has it. This is also the way to check "does the learner have this word?": the AI corrects misspellings first, so ubiquitus still finds a saved ubiquitous. Never saves. Usually a few seconds; the result is cached for 30 minutes per learner, so a following POST /agent/vocab for the same word is instant.

Body
FieldTypeDescription
wordstring, 1–100 charactersrequiredEnglish or Russian word or short phrase.
contextstring, ≤500optionalThe sentence the word came from and the meaning to use, e.g. We need to account for every endpoint. Meaning: keep track of. The card then uses that sense instead of the most common one. Send the same value to resolve and add, so the saved word is the card that was shown.
Request
curl -X POST https://api.lingoborn.com/agent/vocab/resolve \
  -H "Authorization: Bearer $AGENT_SECRET" -H "X-User-Email: learner@example.com" \
  -H "Content-Type: application/json" -d '{"word":"serendipity"}'
Response 200
{
  "card": {
    "english": "serendipity",
    "russian": "счастливая случайность",
    "pronunciation": "/ˌserənˈdɪpəti/",
    "explanationEn": "Finding something good by chance.",
    "explanationRu": "Неожиданная удачная находка.",
    "examples": [ { "en": "Meeting her was pure serendipity.", "ru": "Встреча с ней была чистой случайностью." } ],
    "synonyms": [ "chance", "luck" ],
    "category": "General",
    "architecture": { "type": "word", "root": "serendip-", "rootConceptRu": "…", "derivationsRu": [ "…" ] }
  },
  "exists": false,
  "match": null
}
examples has up to 3 items and synonyms up to 5. category is the AI-suggested group. architecture is the word's morphology (root, inflections, derivations; or phrase type and parts for phrases) with empty fields removed, or null. exists / match are checked against card.english, so a Russian input finds the saved English word.
POST/agent/vocabAgent secret

Save a word to the learner's dictionary as to_learn. Call only after the learner has confirmed. Duplicates are detected before and after AI enrichment (English or Russian, case-insensitive), and today's added stat is incremented for new words.

Body
FieldTypeDescription
wordstring, 1–100 charactersrequiredEnglish or Russian word or short phrase.
contextstring, ≤500optionalThe sentence the word came from and the meaning to use, e.g. We need to account for every endpoint. Meaning: keep track of. The card then uses that sense instead of the most common one. Send the same value to resolve and add, so the saved word is the card that was shown.
categorystring, 1–60optionalCategory to save into. Default: the AI-suggested category, else General.
Request
curl -X POST https://api.lingoborn.com/agent/vocab \
  -H "Authorization: Bearer $AGENT_SECRET" -H "X-User-Email: learner@example.com" \
  -H "Content-Type: application/json" -d '{"word":"serendipity"}'
Response 201 — created
{
  "created": true,
  "word": { "id": 413, "english": "serendipity", "russian": "счастливая случайность", "category": "General", "state": "to_learn" },
  "totalWords": 143
}
Response 200 — already saved
{
  "created": false,
  "duplicate": true,
  "word": { "id": 413, "english": "serendipity", … },
  "totalWords": 143
}
GET/agent/vocab/summaryAgent secret

Compact totals the tutor can quote: how many words, how many per learning stage, top categories, how many per part of speech, words added today, and the learner's level. For the full breakdown use GET /v1/words/summary.

Request
curl https://api.lingoborn.com/agent/vocab/summary \
  -H "Authorization: Bearer $AGENT_SECRET" -H "X-User-Email: learner@example.com"
Response 200
{
  "total": 143,
  "byState": { "to_learn": 90, "practiced": 33, "learned": 20 },
  "topCategories": [ { "category": "Travel", "count": 40 }, { "category": "Food", "count": 25 } ],
  "byPartOfSpeech": { "noun": 64, "verb": 38, "adjective": 21, "pronoun": 3, "unknown": 17 },
  "addedToday": 3,
  "level": "B1",
  "wordCardMode": "translation"
}
byState always includes all three keys. topCategories has at most 5 items. byPartOfSpeech only lists kinds the learner has (noun, verb, phrasal_verb, adjective, adverb, pronoun, preposition, conjunction, determiner, numeral, interjection, phrase); unknown = words saved before part of speech was recorded. addedToday counts the current UTC day and includes words added in the app.
GET/agent/grammar/summaryAgent secret

The learner's Grammar section, for questions like "how many grammar topics do I have" or "what's in progress". Topics the learner turned off are left out. Read-only.

Request
curl https://api.lingoborn.com/agent/grammar/summary \
  -H "Authorization: Bearer $AGENT_SECRET" -H "X-User-Email: learner@example.com"
Response 200
{
  "total": 3,
  "byStatus": { "learning": 2, "queued": 0, "done": 1 },
  "dueNow": 1,
  "topics": [
    { "topicKey": "articles", "title": "Articles: a / an / the / no article", "titleRu": "Артикли",
      "status": "learning", "streak": 5, "goal": 8, "days": 2, "daysGoal": 3,
      "due": true, "nextAt": "2026-11-05T09:00:00.000Z", "doneAt": null, "accuracy7": 80, "mistakes30d": 4 }
  ]
}
status: learning (in progress; no active-topic cap), done (mastered: goal correct in a row on daysGoal days; gets check-ups). queued remains as a compatibility count and is always 0; existing queued records are migrated to learning. Due dates guide practice but do not block a selected topic. accuracy7 is % correct over the last 7 days, null with no answers. Topics are ordered learning → done.