Knowledge API

Free-text note ingest with AI classification, plus structured entries, connections, and comments. Mounted at /api/knowledge. The vocabulary module (/api/vocabulary) writes the same underlying table with a narrower surface.

Note ingest (the interesting endpoint)#

POST /api/knowledge/notes with scope knowledge:write. Three accepted body shapes (strict: unknown keys are 400):

{"text": "today I learned gracias means thank you in Spanish"}
{"text": "...", "source": "Nibbler"}
{"notes": [{"text": "...", "source": {"book": "War and Peace", "location": "ch. 3"}}]}

• text trimmed 1..5000. source is a string (becomes {app}) or an object with app/book/author/location/rawContext.
• Single: 201 {entries:[entry]}. Batch (1..50): 201 all-ok, 207 {entries, failures:[{index, text, error}]} on partial failure, 502 when every note failed or the LLM chain is exhausted (retryable).
• Caller-supplied source fields beat classifier-extracted ones. No cross-request dedup by design; within one batch, duplicate (word, language) pairs are silently dropped.
• Rate: 30/min single, 5/min batch (separate buckets).

Every other write here is rate limited per PAT as well (browser sessions bypass; 429 with Retry-After: 60): entry create, edit, delete and bulk-delete plus connection create and delete share one 30/min bucket, POST /entries/:id/enrich has its own 10/min bucket because each call runs the model, and comment create, edit and delete have their own 30/min bucket.

Entries#

?location= matches cards whose memorizationLocations array contains that place, case-insensitively (max 120 chars, same bound as a single location on PUT). ?excludeLocation= is the inverse with the same bounds: cards NOT yet memorized at that place, including cards with no locations at all, so a place nothing has been memorized at returns every card. GET /api/knowledge/locations (public) returns {locations: string[]}: every distinct location across all cards, deduped case-insensitively and sorted. That list is what the browse filter's dropdown is built from. Its siblings GET /labels, GET /languages and GET /categories return the same shape for their dimensions.

To mark or unmark a place, send addMemorizationLocations or removeMemorizationLocations (each up to 50 names of up to 120 chars) rather than a full memorizationLocations list. The deltas are applied to the card as it is stored at that moment, under a row lock that practice mode also takes when it records a newly memorized place, so a place recorded after you read the card is kept. Removal is case-insensitive and adding a place the card already holds, in any casing, changes nothing. A full list overwrites whatever is stored, so only send it when you mean to replace the set.

Cards from notes#

Inline notes and Explain answers on journal entries, blog posts, knowledge cards and public courses also arrive here: each new note is classified into a card with the same pipeline as POST /notes, from the selected words and the note only, with source.app set to journal, blog, knowledge or course (since SHAN-653; a note on a private course never becomes a card). See AI and Reader Notes API.

Recite#

Recite your own cards from memory, one place at a time. Both routes need scope knowledge:write and work on the caller's cards: ones they created, plus legacy rows with no recorded creator (the same set PUT /entries/:id lets them write).

• judge says what decided: match (near-verbatim, no model call), ai (a small free model; Groq gpt-oss-20b first) or similarity (local embeddings, used only when every model provider is down).
• hint is {kind, label, text}; send the attempt number and attempt N gets hint N, gentlest first: example (or topics when the card has no example, or its example contains the answer), opening (the first few words, skipped for answers under four words), then shape (each word's first letter, the rest masked). Past the last hint, the last one repeats.
• Miss feedback never names what is missing. Feedback that would is replaced server-side; the hints are the only part of a miss that reveals the answer.
• Rate (PATs): 30/min deck, 60/min attempts.

Connections (synonym, antonym, related, translation, root): GET/POST /connections, DELETE /connections/:id, scope knowledge:write. POST returns 201 {connection}; 400 connecting an entry to itself, 404 unknown entry id, 403 unless you own both entries, 409 if that typed edge already exists. DELETE returns {ok: true}; 404 unknown, 403 unless you own both endpoint entries. Entries with no recorded creator (legacy rows) count as yours for this check. Both modules enforce the same rule on the same table, so neither path can link or unlink someone else's entries.

Comments: same shape as journal comments (GET/POST /entries/:id/comments, PATCH/DELETE /comments/:id, scope comments:write, snake_case parent_comment_id, one reply level). The parent must be a top-level comment on the same entry, or the POST is a 400; deleting a comment keeps its replies as top-level comments.

Vocabulary module differences#

Full route table: Vocabulary API. The differences that bite most often:

• GET /api/vocabulary/words search matches the word column only; list key is {words} not {entries}. Both modules match search literally -- do not escape % or _ yourself, see Text search.
• Duplicate check is (word, language) with no category dimension.
• All writes use scope knowledge:write (there is no vocabulary:write), bucket vocabulary-writes 30/min, enrich 10/min.