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
Backend
/ai/* routes → Infobip AI ComponentsLiveChat client →
POST /livechat/token, then Infobip LiveChatMobile synchronization →
POST /syncAgentOS tutor →
/agent/* tools (machine-to-machine secret + learner email; never a user JWT)
| Audience | Use these routes | Authentication |
|---|---|---|
| Health checks | GET /health | None |
| Mobile and web users | /auth/*, /me, /v1/* | User JWT |
| Signed-in AI features | /ai/* | User JWT |
| LiveChat setup | POST /livechat/token | User JWT |
| Mobile offline sync | POST /sync | User 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.
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
| Topic | Detail |
|---|---|
| Content type | Request bodies are application/json. Set Content-Type: application/json on POST/PUT. |
| Pagination | GET /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. |
| Projection | fields=compact (default) returns a light record; fields=full returns the whole card. |
| Deletes | Deleted rows are hidden everywhere (soft-deleted); reads mirror exactly what the app shows. |
| Timestamps | ISO-8601 UTC (e.g. 2026-09-11T09:13:00.000Z). |
Errors
Standard HTTP status codes; the body is always { "error": "…" }.
| Status | Meaning |
|---|---|
400 | Invalid input or a non-numeric :id. |
401 | Missing, invalid, or expired bearer token — log in again. |
404 | Resource not found (or not yours). |
409 | Conflict (e.g. registering an email that already exists). |
429 | Too many requests (/agent/*: more than 60 per minute per learner). See the Retry-After header. |
500 | Server error. |
502 | Upstream AI request failed. |
503 | Feature not configured on the server (/agent/* without an agent secret). |
System
Lightweight liveness check for the backend process.
curl https://api.lingoborn.com/health
{ "ok": true, "service": "lingoborn-backend" }
Auth
Create an account and receive a token.
| Field | Type | |
|---|---|---|
email | string | required |
password | string (min 6) | required |
name | string | required |
country, gender, learningGoal, level | string | optional |
knownLanguages, interests | string[] | optional |
dailyGoal | integer | optional |
reminders | boolean | optional |
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.
| Field | Type | |
|---|---|---|
email | string | required |
password | string | required |
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" } }
401 { "error": "Invalid email or password." }.Profile
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.
| Field | Type |
|---|---|
name, country, gender, learningGoal, level | string |
knownLanguages, interests | string[] |
dailyGoal | integer |
reminders | boolean |
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, … } }
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.
| Field | Type |
|---|---|
image | base64 string or data:image/…;base64, URL. JPEG, PNG or WebP, max 2 MB. |
curl -X PUT https://api.lingoborn.com/me/avatar \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "{\"image\":\"$(base64 -i avatar.jpg)\"}"
{ "user": { "id": 1, "avatarUrl": "/avatars/1-3f9c0a7d2b1e4c5f6a7b8c9d.jpg", … } }
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.Permanently delete the account and all its data (words, decks, stories, groupings, stats cascade).
{ "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.
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).
{ "word": "resilient", "context": "(optional) The sentence it came from. Meaning: …" }
{ "output": { … } }
context (optional, ≤500 characters): the sentence the word came from plus the meaning to use; the card is then in that sense.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.
{ "text": "We need to account for every endpoint." }
{ "kind": "sentence",
"sentences": [ { "en": "We need to account for every endpoint.", "ru": "Нам нужно учесть каждый эндпоинт." } ],
"items": [ { "english": "account for", "russian": "учитывать", "kind": "phrase", "sentenceIndex": 0 } ] }
sentenceIndex points into sentences. 400 for empty or over-long text, 502 if the AI fails.Generate a learning story using a category and a list of words.
{ "category": "Food", "words": ["apple", "bread"] }
{ "output": { … } }
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.
| Field | Type | |
|---|---|---|
category | string | required |
count | positive integer | required |
existingWords | string[] | required |
{ "output": { … } }
Group words in a category into synonym/antonym or learning clusters.
{ "category": "Travel", "words": ["journey", "trip"] }
{ "output": { … } }
Start a background filler job for a larger batch. The request returns immediately with 202; the server generates and persists new words in batches.
| Field | Type | |
|---|---|---|
category | string | required |
target | positive integer, max 50 | required |
existingWords | string[] | optional, defaults to [] |
{ "job": { "id": "…", "kind": "filler", "category": "Travel", "target": 20, "added": 0, "status": "running", "error": null } }
Find the latest background generation job for the signed-in user.
| Param | Purpose |
|---|---|
category | match one category |
status | match a status such as running, completed or failed |
{ "job": { … } } // or { "job": null }
Read one generation job. Jobs are scoped to the authenticated user; another user's job returns 404.
{ "job": { "id": "…", "kind": "filler", "category": "Travel", "target": 20, "added": 14, "status": "completed", "error": null } }
Integrations
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.
{ "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.
jwt with LiveChat's mobile session API.Push local mobile changes, then pull rows changed since the last server cursor. The endpoint is authenticated and user-scoped.
{
"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": []
}
}
{ "serverTime": "2026-09-11T09:14:00.000Z", "changes": { "words": [ … ], "decks": [ … ], "stories": [ … ], "groupings": [ … ], "dailyStats": [ … ] } }
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
List words with filtering, sorting and cursor pagination.
| Param | Values | Default |
|---|---|---|
fields | compact · full | compact |
limit | 1–200 | 50 |
cursor | the nextCursor from a prior page | — |
sort | created · alpha · updated | created |
category | exact group name, e.g. Food | — |
state | to_learn · practiced · learned | — |
q | search in english/russian (case-insensitive) | — |
partOfSpeech | exact, e.g. verb (empty until enriched) | — |
createdAfter / createdBefore | date, e.g. 2026-01-01 | — |
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"
}
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.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": [ … ] }
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.
| Field | Type | |
|---|---|---|
english, russian | string | required |
category, state, partOfSpeech | string | optional |
pronunciation, example, exampleRu, imageEmoji, explanationEn, explanationRu, audioUrl | string | optional |
synonyms, examples, architecture | array/object | optional |
force | boolean | optional; create even if a duplicate exists |
curl -X POST https://api.lingoborn.com/v1/words \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"english":"resilient","russian":"стойкий","category":"Work"}'
{ "id": 43, "english": "resilient", "russian": "стойкий", … }
200 and includes duplicate: true. New cards start in to_learn unless another valid state is supplied.Update any supplied word-card fields, or reset practice progress with { "reset": true }.
curl -X PATCH https://api.lingoborn.com/v1/words/43 \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"category":"Work","state":"practiced"}'
{ "id": 43, "category": "Work", "state": "practiced", … }
Soft-delete one word. It disappears from normal reads and is retained as a sync tombstone.
{ "ok": true }
Bulk-create cards or apply a category/state change to selected words.
// Create cards { "create": [ { "english": "calm", "russian": "спокойный" } ] } // Update by ids or filter { "ids": [43, 44], "set": { "category": "Work" } } { "filter": { "state": "to_learn" }, "set": { "state": "practiced" } }
{ "created": 1 } // create operation
{ "updated": 2 } // set operation
Decks & categories
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.
| Field | Type | |
|---|---|---|
name | string, trimmed, 1–80 characters | required |
curl -X POST https://api.lingoborn.com/v1/decks \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Doctor visit"}'
{ "deck": { "id": 7, "uuid": "…", "name": "Doctor visit", "createdAt": "…", "updatedAt": "…" } }
400 for an empty or overlong name and 409 when that name is already used by a deck or category.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.
curl https://api.lingoborn.com/v1/categories -H "Authorization: Bearer $TOKEN"
{ "categories": [
{ "category": "Food", "wordCount": 12, "hasGrouping": true, "storyCount": 2 },
{ "category": "Doctor visit", "wordCount": 0, "hasGrouping": false, "storyCount": 0 }
] }
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-…" }
Rename a category across the authenticated user's words, stories, grouping and matching persistent deck records when possible.
{ "newName": "Healthy Food" }
{ "from": "Food", "to": "Healthy Food", "renamedWords": 12, "renamedStories": 2, "renamedDecks": 1 }
Create or replace the synonym/antonym clusters for a category.
{ "clusters": [ { "label": "Movement", "words": ["walk", "stroll"] } ] }
{ "category": "Travel", "clusters": [ … ], "updatedAt": "2026-09-…" }
Stories
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": [ … ] }
Persist a story that was generated through /ai/story or supplied by another trusted client.
| Field | Type | |
|---|---|---|
category, story | string | required |
title | string | optional |
wordsUsed | string[] | optional |
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"]}'
{ "id": 3, "uuid": "…", "category": "Food", "title": "Breakfast", … }
Soft-delete one story. It is hidden from normal reads and retained for synchronization.
{ "ok": true }
Practice
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.
{ "wordId": 43, "correct": true }
{ "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.
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.
{ "topics": [ { "topicKey": "articles", "status": "learning", "streak": 2, "due": true, … } ], "dueCount": 1 }
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.
| Param | Purpose |
|---|---|
topic | One learning or completed topic key to practice now, even when it is not due; omit to mix topics due now. |
{ "items": [ { "id": "…", "topicKey": "articles", "kind": "choose", "text": "I saw ___ doctor this morning.", "options": ["a", "an", "the", "—"] } ] }
Submit an answer for server-side grading and update topic progress. Check-ups for completed topics are tracked by the server.
{ "itemId": "…", "answer": "a", "topicKey": "articles" }
400 for invalid input; 404 when the item or topic is unavailable.
Turn one topic off or turn it back on.
{ "status": "off" }
{ "topicKey": "articles", "status": "off" }
Dismiss a logged mistake so it no longer contributes to topic offers or relapse handling.
{ "ok": true }
Stats
Daily learning stats plus totals over the range.
| Param | Format |
|---|---|
from | YYYY-MM-DD |
to | YYYY-MM-DD |
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 }
}
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.
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
| Rule | Detail |
|---|---|
| Learner scope | Every read and write is limited to the learner resolved from X-User-Email. |
| Identity source | The email must come from the signed-in LiveChat personalization (CDP), never from text the learner typed in chat. |
| Rate limit | 60 requests per minute per learner → 429 with Retry-After. |
| Sync | Saved 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. |
| Status | When |
|---|---|
401 | Missing or wrong agent secret (including a user JWT sent instead). |
400 | Missing or invalid X-User-Email (usually an empty chatbot attribute), or invalid input. |
404 | No Lingoborn account for that email. |
429 | Rate limit exceeded. |
502 | AI word lookup failed; nothing was saved. |
503 | AGENT_API_SECRET is not configured on the server. |
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.
| Field | Type | Description | |
|---|---|---|---|
word | string, 1–100 characters | required | English or Russian word or short phrase. |
context | string, ≤500 | optional | The 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. |
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"}'
{
"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.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.
| Field | Type | Description | |
|---|---|---|---|
word | string, 1–100 characters | required | English or Russian word or short phrase. |
context | string, ≤500 | optional | The 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. |
category | string, 1–60 | optional | Category to save into. Default: the AI-suggested category, else General. |
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"}'
{
"created": true,
"word": { "id": 413, "english": "serendipity", "russian": "счастливая случайность", "category": "General", "state": "to_learn" },
"totalWords": 143
}
{
"created": false,
"duplicate": true,
"word": { "id": 413, "english": "serendipity", … },
"totalWords": 143
}
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.
curl https://api.lingoborn.com/agent/vocab/summary \ -H "Authorization: Bearer $AGENT_SECRET" -H "X-User-Email: learner@example.com"
{
"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.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.
curl https://api.lingoborn.com/agent/grammar/summary \ -H "Authorization: Bearer $AGENT_SECRET" -H "X-User-Email: learner@example.com"
{
"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.