kanji-buddy

Endpoint reference

All thirty-six of them. Everything here is relative to https://kanjibuddy.mblrc.me/api/v1 and needs a bearer token.

The rules these all share — auth, paging, filtering, ETags, error shapes — are on Conventions and are not repeated per endpoint. Endpoints marked App-specific have no WaniKani equivalent.

Account

GET /user

The account, its level, and the client-side preferences blob.

{
  "object": "user",
  "url": "https://kanjibuddy.mblrc.me/api/v1/user",
  "data_updated_at": "2026-08-20T09:51:12.120Z",
  "data": {
    "id": "49a9bb31-9915-4c4c-988e-8fc5709a71c6",
    "username": "mblrc",
    "level": 3,
    "profile_url": null,
    "started_at": "2026-07-23T06:29:04.713Z",
    "current_vacation_started_at": null,
    "timezone": "Asia/Manila",
    "subscription": {
      "type": "recurring",
      "active": true,
      "period_ends_at": null,
      "max_level_granted": 60
    },
    "preferences": { "heat_map_view": "month" }
  }
}

• id is a UUID string — the only id in the API that is not numeric.
• current_vacation_started_at is set while the SRS clock is paused. See GET /vacation — a client that serves lessons or reviews must check it, because the underlying rows stay due while it is set.
• subscription exists for WaniKani compatibility. This is a private server: it is always active at level 60 and there is nothing to buy. Do not gate features on it.
• timezone is ours, not WaniKani’s — an IANA zone name, null until set. It decides what “today” means for /review_stats, /days_studied, the study streak and the quiet hours of push notifications. A new install should set it.
• level is the level you have actually reached — the highest level in /level_progressions, computed per request. It is not the users.level column, which is set when an account is created and never advances. Before v1.2.1 this endpoint returned that column, so clients reading it showed Level 1 forever while /dashboard showed the real number.

PUT /user

Update preferences, timezone, or both. Responds with the same body as GET /user. Accepts either a bare object or WaniKani’s { "user": { … } } wrapper.

curl -X PUT https://kanjibuddy.mblrc.me/api/v1/user \
  -H "Authorization: Bearer $KANJIBUDDY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "timezone": "Asia/Manila",
        "preferences": { "lessons_batch_size": 8, "default_voice_gender": "female" }
      }'

timezone is validated against the runtime’s own tz database — "GMT+8" and "Manila" are 422, "Asia/Manila" is fine.

Known preference keys

The server reads these. Anything else you store is yours to interpret — it is handed back untouched.

Periods are today, past_7_days, this_month, past_28_days, this_year, past_365_days, all_time. Widget keys, in the order the dashboard shows them: forecast, level_progress, item_spread, extra_study, recent_mistakes, critical_items, recently_unlocked, recently_burned, study_streak, correct_percentage, reviews_completed.

GET /vacation · App-specific

Whether the SRS clock is paused, and for how long. days_away is whole days and is 0 on the first day.

{
  "object": "report",
  "url": "https://kanjibuddy.mblrc.me/api/v1/vacation",
  "data_updated_at": "2026-08-28T04:10:02.881Z",
  "data": {
    "started_at": "2026-08-16T09:12:44.000Z",
    "days_away": 12
  }
}

PUT /vacation · App-specific

Turn it on or off. The body is { "active": true } or { "active": false } — anything else is a 422. Responds with the same body as the GET.

curl -X PUT https://kanjibuddy.mblrc.me/api/v1/vacation \
  -H "Authorization: Bearer $KANJIBUDDY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "active": true }'

Content

GET /subjects

Radicals, kanji, vocabulary. ~9,400 rows, shared by every user, effectively static since 2012. per_page is 1000 here.

The four subject types are radical, kanji, vocabulary and kana_vocabulary.

{
  "id": 440,
  "object": "kanji",
  "url": "https://kanjibuddy.mblrc.me/api/v1/subjects/440",
  "data_updated_at": "2026-07-07T05:30:10.285Z",
  "data": {
    "slug": "一",
    "level": 1,
    "characters": "一",
    "meanings": [
      { "meaning": "One", "primary": true, "accepted_answer": true }
    ],
    "readings": [
      { "type": "onyomi",  "primary": true,  "reading": "いち", "accepted_answer": true },
      { "type": "onyomi",  "primary": false, "reading": "いつ", "accepted_answer": true },
      { "type": "kunyomi", "primary": false, "reading": "ひと", "accepted_answer": false },
      { "type": "nanori",  "primary": false, "reading": "かず", "accepted_answer": false }
    ],
    "auxiliary_meanings": [ { "type": "whitelist", "meaning": "1" } ],
    "component_subject_ids": [1],
    "amalgamation_subject_ids": [2467, 2468, 2477],
    "visually_similar_subject_ids": [],
    "meaning_mnemonic": "Lying on the <radical>ground</radical> is …",
    "meaning_hint": "To remember the meaning of <kanji>One</kanji> …",
    "reading_mnemonic": "As you're sitting there next to <kanji>One</kanji> …",
    "reading_hint": "Make sure you feel the ridiculously <reading>itchy</reading> …",
    "document_url": "https://www.wanikani.com/kanji/%E4%B8%80",
    "lesson_position": 25,
    "spaced_repetition_system_id": 2,
    "hidden_at": null,
    "created_at": "2012-02-27T19:55:19.000000Z"
  }
}

The three fields that decide grading

Getting these wrong is the most common way to build a quiz that lies to the learner.

auxiliary_meanings carry type: "whitelist" (also accept it) and type: "blacklist" (explicitly wrong, usually a confusable near-synonym — mark it incorrect rather than nudging). Radicals and kana_vocabulary have no readings and are quizzed on meaning only.

Two fields WaniKani does not have

Both are scraped from subject pages, and both are omitted entirely when there is nothing to show — so data.patterns_of_use?.length is the whole test for whether to render the section, and a stock WaniKani client sees an unchanged payload.

patterns_of_use is shaped for the two-pane layout WaniKani renders it in — the array is the left-hand list, in the page’s own order, and each entry’s collocations are the right-hand panel:

patterns_of_use.map((p) => p.pattern)   // left pane
patterns_of_use[selected].collocations  // right pane

Each collocation is { en, ja } — deliberately the same shape as context_sentences, so one component renders both.

Vocabulary-only fields

{
  "url": "https://files.wanikani.com/r8jqaotmr178the7vwce82usz0ur",
  "content_type": "audio/webm",
  "metadata": {
    "gender": "male",
    "source_id": 2711,
    "pronunciation": "いち",
    "voice_actor_id": 2,
    "voice_actor_name": "Kenichi",
    "voice_description": "Tokyo accent"
  }
}

Two rendering traps

Radicals can have characters: null — they exist only as an image. Fall back to slug and fetch the SVG from /radicals/{slug}.svg on the web app’s origin.

Mnemonic fields contain WaniKani’s markup, not HTML. meaning_mnemonic, reading_mnemonic, meaning_hint and reading_hint carry inline <radical>, <kanji>, <vocabulary>, <reading>, <ja>, <b> and <i> tags. Parse them and style each in your own palette rather than injecting them — that colour-coding is how a learner tells a radical from a kanji mid-sentence.

GET /subjects/{id}

One subject as a resource envelope. Same data as above.

GET /search · App-specific

Subjects matching what someone typed, best first. WaniKani has no search endpoint and its /subjects filters only by id, slug, type and level — none of which help a person who remembers a word but not where it lives.

{
  "object": "report",
  "url": "https://kanjibuddy.mblrc.me/api/v1/search",
  "data_updated_at": null,
  "total_count": 3,
  "data": [
    {
      "id": 2604,
      "object": "vocabulary",
      "level": 3,
      "characters": "お父さん",
      "slug": "お父さん",
      "meanings": ["Father", "Dad"],
      "reading": "おとうさん"
    }
  ]
}

Four fields are matched, because there are four things a person remembers about an item: the characters, any meaning (not only the primary one), any reading, and the slug. Withdrawn subjects (hidden_at) never appear — they are unreachable everywhere else and would be a dead link from here.

Ordering is exact match, then starts-with, then contains, and within each, the lower level first — you are likelier to want a word you have met. Render in the order given.

data_updated_at is deliberately null: the answer depends on the query string rather than on when content changed, and a timestamp here would let one search be served from another’s cache.

GET /spaced_repetition_systems

The interval tables. Two systems: one for dictionary subjects, one for everything you study. Filters: ids, updated_after.

{
  "id": 1,
  "object": "spaced_repetition_system",
  "data": {
    "name": "Default system for dictionary subjects",
    "stages": [
      { "position": 0, "interval": null,  "interval_unit": "seconds" },
      { "position": 1, "interval": 14400, "interval_unit": "seconds" },
      { "position": 2, "interval": 28800, "interval_unit": "seconds" }
    ]
  }
}

Each subject names its system in data.spaced_repetition_system_id. A client never needs this to schedule anything — the server computes available_at on every review. Fetch it only to display an interval (“next review in 4 hours”).

GET /voice_actors

WaniKani’s pronunciation voices. Filters: ids, updated_after. Empty unless the voice actor data has been imported; the audio URLs themselves live on the vocabulary subject, in data.pronunciation_audios.

Study state

GET /assignments

The join between you and a subject: what you have unlocked, its SRS stage, and when it is next due. This is the table a study app actually runs on.

{
  "id": 76,
  "object": "assignment",
  "url": "https://kanjibuddy.mblrc.me/api/v1/assignments/76",
  "data_updated_at": "2026-08-15T15:04:29.592Z",
  "data": {
    "created_at": "2026-08-13T11:51:02.790Z",
    "subject_id": 440,
    "subject_type": "kanji",
    "srs_stage": 2,
    "unlocked_at": "2026-08-11T11:51:02.790Z",
    "started_at": "2026-08-14T15:53:54.404Z",
    "passed_at": null,
    "burned_at": null,
    "available_at": "2026-08-15T14:53:54.404Z",
    "resurrected_at": null,
    "hidden": false
  }
}

Reading the lifecycle

The four timestamps are a state machine, and the combination tells you where an item is:

srs_stage is 0 before a lesson is started, 1–8 in the cycle, 9 when burned. The dashboard groups them: Apprentice 1–4, Guru 5–6, Master 7, Enlightened 8, Burned 9. passed_at is sticky — a later wrong answer drops the stage but does not clear it. GET /assignments/{id} returns one.

PUT /assignments/{id}/start

Turn a lesson into a review item: stage 0 → the system’s starting stage, and available_at gets its first schedule. Call this once per item when a lesson batch is taught, before the first POST /reviews for it. Responds with the updated assignment.

The body is optional — all three of these work, and started_at defaults to now:

# nothing at all
curl -X PUT https://kanjibuddy.mblrc.me/api/v1/assignments/76/start \
  -H "Authorization: Bearer $KANJIBUDDY_TOKEN"

# bare object
-d '{ "started_at": "2026-08-14T15:53:54.404Z" }'

# WaniKani's wrapper
-d '{ "assignment": { "started_at": "2026-08-14T15:53:54.404Z" } }'

GET /review_statistics

Per-subject accuracy, one row per subject you have reviewed.

Filters: ids, subject_ids, subject_types, hidden, updated_after, plus percentages_greater_than and percentages_less_than — both of which are inclusive despite their names, so ?percentages_less_than=75 returns rows at exactly 75 too.

{
  "id": 19,
  "object": "review_statistic",
  "data": {
    "created_at": "2026-08-13T11:52:47.473Z",
    "subject_id": 440,
    "subject_type": "kanji",
    "meaning_correct": 2,
    "meaning_incorrect": 0,
    "meaning_max_streak": 2,
    "meaning_current_streak": 2,
    "reading_correct": 2,
    "reading_incorrect": 0,
    "reading_max_streak": 2,
    "reading_current_streak": 2,
    "percentage_correct": 100,
    "hidden": false
  }
}

percentage_correct is over meaning and reading together, and is 100 on a row with no answers yet. Below 75 is what KanjiBuddy calls “critical” — the leeches. Radicals and kana_vocabulary never accrue reading counts. Rows are created by the first POST /reviews for a subject; there is no endpoint to create or edit one.

GET /level_progressions

When you reached each level. Filters: ids, updated_after.

{
  "id": 1,
  "object": "level_progression",
  "data": {
    "created_at": "2026-07-23T06:29:05.535Z",
    "level": 1,
    "unlocked_at": "2026-07-23T06:29:04.713Z",
    "started_at": "2026-07-23T06:29:04.713Z",
    "passed_at": null,
    "completed_at": null,
    "abandoned_at": null
  }
}

Your current level is the highest level here, which is what the server itself uses — the level on /user is a fallback for an account with no progressions yet.

GET /resets

Level resets. Filters: ids, updated_after. Empty unless you have reset, and nothing in the API creates one.

Notes

GET /study_materials

Your notes and personal synonyms. Filters: ids, subject_ids, subject_types, hidden, updated_after.

{
  "id": 2,
  "object": "study_material",
  "data": {
    "created_at": "2026-08-14T14:59:09.552Z",
    "subject_id": 441,
    "subject_type": "kanji",
    "meaning_note": null,
    "reading_note": "Ni",
    "meaning_synonyms": [],
    "hidden": false
  }
}

POST /study_materials

Create the note for a subject — one per subject per user. Responds 201 with the created resource. Accepts the { "study_material": { … } } wrapper too.

curl -X POST https://kanjibuddy.mblrc.me/api/v1/study_materials \
  -H "Authorization: Bearer $KANJIBUDDY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "subject_id": 441,
        "meaning_note": "Two lines, two things.",
        "reading_note": "Ni",
        "meaning_synonyms": ["a pair"]
      }'

subject_type is filled in from the subject; do not send it.

PUT /study_materials/{id}

Update meaning_note, reading_note, meaning_synonyms. Omitted fields are left alone; null clears a note; [] clears the synonyms.

Note the id is the study material’s, not the subject’s — find it with GET /study_materials?subject_ids=441.

Answering

POST /reviews

The only endpoint that moves the SRS. Submit one answered item; the server runs the engine, updates the assignment, updates the statistics, writes the review log, and handles unlocks and level-ups in a single transaction.

curl -X POST https://kanjibuddy.mblrc.me/api/v1/reviews \
  -H "Authorization: Bearer $KANJIBUDDY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "assignment_id": 76,
        "incorrect_meaning_answers": 0,
        "incorrect_reading_answers": 1
      }'

Response — 201

The created review, plus everything the write changed, so a client needs no follow-up reads:

{
  "id": 412,
  "object": "review",
  "data": {
    "created_at": "2026-08-15T15:04:29.592Z",
    "assignment_id": 76,
    "subject_id": 440,
    "starting_srs_stage": 2,
    "ending_srs_stage": 1,
    "incorrect_meaning_answers": 0,
    "incorrect_reading_answers": 1,
    "spaced_repetition_system_id": 2
  },
  "resources_updated": {
    "assignment": { "…": "the updated assignment resource" },
    "review_statistic": { "…": "the updated review_statistic resource" }
  }
}

starting_srs_stage → ending_srs_stage is what to animate. resources_updated.assignment carries the new available_at.

The engine

• Correct → stage +1.
• Wrong → stage − ceil(incorrect / 2) × (stage ≥ 5 ? 2 : 1), floored at the item’s starting stage. A wrong answer at Guru or above costs double.
• available_at is the new stage’s interval from now, floored to the top of the hour.
• Reaching stage 5 sets passed_at, which unlocks dependents — radicals unlock their kanji, kanji unlock their vocabulary — and, for kanji, may trigger a level-up once 90% of the level’s kanji are passed.

All of that happens server-side inside the transaction. A client submits an answer and reads back the result; it should never compute a stage itself. See SRS engine.

GET /reviews returns nothing. Deprecated in WaniKani, and here it is an empty collection with total_count: 0 so a compatible client does not 404. The review log is not queryable — the aggregates it would be used for are served by /review_stats and /heat_map.

Screens

GET /summary

Lessons available now, and reviews bucketed into the next 24 hourly slots. WaniKani’s endpoint, unchanged.

{
  "object": "report",
  "data": {
    "lessons": [
      { "available_at": "2026-08-21T18:00:00.000Z", "subject_ids": [447, 448, 449] }
    ],
    "reviews": [
      { "available_at": "2026-08-21T18:00:00.000Z", "subject_ids": [471, 465, 440] },
      { "available_at": "2026-08-21T19:00:00.000Z", "subject_ids": [] }
    ],
    "next_reviews_at": "2026-08-22T16:00:00.000Z"
  }
}

reviews is always 24 entries, one per hour starting at the current hour, and most are usually empty. The first entry holds everything already due — including items that came due days ago — so data.reviews[0].subject_ids.length is “reviews waiting right now”. next_reviews_at is when the next non-empty batch arrives, or null if nothing is scheduled.

GET /dashboard · App-specific

Everything the home screen needs in one request, instead of the ~15 round trips the resource endpoints would take to produce the same counts. The aggregation happens in Postgres and only the numbers come back.

{
  "object": "report",
  "data": {
    "username": "mblrc",
    "level": 3,
    "lessons": { "available": 13, "subject_ids": [447, 448] },
    "lesson_allowance": { "max": 15, "started_today": 3, "remaining": 12 },
    "vacation": { "started_at": null, "days_away": 0 },
    "reviews": { "available": 30, "subject_ids": [471, 465] },
    "forecast": [
      { "available_at": "2026-08-22T16:00:00.000Z", "count": 1, "cumulative": 31 }
    ],
    "level_progress": {
      "level": 1,
      "radicals":   { "passed": 10, "total": 25 },
      "kanji":      { "passed": 0,  "total": 18 },
      "vocabulary": { "passed": 0,  "total": 37 },
      "kanji_to_level_up": 17
    },
    "item_spread": {
      "apprentice":  { "radical": 15, "kanji": 9, "vocabulary": 0, "total": 24 },
      "guru":        { "radical": 10, "kanji": 0, "vocabulary": 0, "total": 10 },
      "master":      { "radical": 0,  "kanji": 0, "vocabulary": 0, "total": 0 },
      "enlightened": { "radical": 0,  "kanji": 0, "vocabulary": 0, "total": 0 },
      "burned":      { "radical": 0,  "kanji": 0, "vocabulary": 0, "total": 0 }
    },
    "recent_mistakes": { "count": 0, "subject_ids": [] },
    "extra_study": {
      "recent_lessons":  { "remaining": 24, "total": 24 },
      "recent_mistakes": { "remaining": 0,  "total": 0 },
      "burned_items":    { "remaining": 0,  "total": 0 }
    },
    "days_studied": {
      "days": 6,
      "first_studied_on": "2026-08-12",
      "last_studied_on": "2026-08-21"
    },
    "study_streak": {
      "current": 1,
      "best": 5,
      "studied_today": true,
      "offerings": 0,
      "today": "2026-08-21",
      "recent_days": [false, true, "…14 booleans, oldest first, ending today"]
    },
    "correct_percentage": {
      "period": "past_7_days",
      "current":  { "reviews": 38, "correct": 36, "percentage": 95 },
      "previous": { "reviews": 36, "correct": 36, "percentage": 100 }
    },
    "reviews_completed": { "…": "same shape, possibly a different period" },
    "item_spread_view": "table",
    "recent_mistakes_mode": "list",
    "hidden_widgets": [],
    "recently_unlocked": [
      {
        "subject": {
          "id": 471,
          "object": "kanji",
          "data": {
            "slug": "六", "level": 2, "characters": "六",
            "meanings": [{ "meaning": "Six", "primary": true, "accepted_answer": true }]
          }
        },
        "at": "2026-08-15T15:04:22.288Z"
      }
    ],
    "recently_burned": [],
    "critical_items": [
      { "subject": { "id": 14, "object": "radical", "data": { "…": "as above" } },
        "percentage_correct": 50 }
    ]
  }
}

• lessons.available is already trimmed to lesson_allowance.remaining — it is what the app will actually offer, not what is unlocked. The unlocked count is /summary.
• On vacation, lessons and reviews both read zero, subject_ids are empty and forecast is [] — the clock is paused, so the next seven days mean nothing. vacation.started_at is what tells the two zeroes apart from having finished everything.
• item_spread folds kana_vocabulary into vocabulary — three columns, not four. If you need the four-way split, count /assignments yourself.
• forecast is the next 7 days. count is what arrives that day; cumulative is the backlog you would face if you did nothing until then. It starts from reviews already waiting, so the first cumulative is usually larger than the first count.
• kanji_to_level_up is how many more of this level’s kanji must reach Guru — 90% of them, rounded up, is the threshold.
• recently_unlocked, recently_burned and critical_items carry at most 12 items each, and the subjects are trimmed to id, object, slug, level, characters and meanings — enough to draw a chip. They are not full subject envelopes. Fetch /subjects?ids=… if you need the rest.
• recent_mistakes is the last 24 hours, worst first.
• item_spread_view, recent_mistakes_mode and hidden_widgets are the user’s preferences, echoed so the screen needs no second request to know how to render itself.
• study_streak.offerings is how many missed days are still forgivable this week — the streak survives up to two, and the third breaks it. recent_days is 14 booleans, oldest first, ending today.

Not cacheable. It ships an ETag, but the value is derived from “now” and will not match. Do not poll it in the background — use /summary for that, and fetch the dashboard when the screen is actually shown.

GET /review_stats · App-specific

Reviews completed in a window, how many were right, and the same figures for the window immediately before, to compare against. period defaults to past_7_days.

{
  "object": "report",
  "data": {
    "period": "past_7_days",
    "current":  { "reviews": 38, "correct": 36, "percentage": 95 },
    "previous": { "reviews": 36, "correct": 36, "percentage": 100 }
  }
}

percentage is null, not 0, when there were no reviews — “nothing to report” and “you got nothing right” are different claims. correct counts items answered right first time.

The two window kinds behave differently, on purpose:

On the 3rd of a month, a review from a week ago is inside past_28_days and outside this_month. all_time has no previous window: previous comes back as zeros with a null percentage.

The dashboard already carries both cards’ numbers for the periods chosen in settings. This endpoint is for asking about a period the user has not chosen, without writing a preference.

GET /days_studied · App-specific

How many distinct days had at least one lesson or review, counted in the user’s timezone. All three fields are null/0 for an account that has never studied.

{
  "object": "report",
  "data": {
    "days": 6,
    "first_studied_on": "2026-08-12",
    "last_studied_on": "2026-08-21"
  }
}

The one genuinely cacheable report: data_updated_at is the last day you studied, so an If-None-Match stays 304 for the rest of the day. The same numbers ride along in /dashboard, so fetch this only when you want the figure on its own.

GET /heat_map · App-specific

A day-by-day count of reviews and lessons, for the contribution-graph grid.

{
  "object": "report",
  "data": {
    "view": "month",
    "offset": 0,
    "from": "2026-08-01",
    "to": "2026-08-31",
    "label": "August 2026",
    "days": [
      { "day": "2026-08-01", "reviews": 0, "lessons": 0 },
      { "day": "2026-08-12", "reviews": 21, "lessons": 24 }
    ]
  }
}

days covers every day in the range including empty ones, so it maps straight onto a grid with no gap filling. label is pre-formatted for the header. An out-of-range offset is a 422 rather than an empty grid.

GET /item_spread · App-specific

The dashboard’s five-by-three grid of counts, with the items in the cells: every started item grouped by SRS stage and then by subject type. This is what the Item Spread screen draws.

{
  "object": "report",
  "url": "https://kanjibuddy.mblrc.me/api/v1/item_spread",
  "data_updated_at": "2026-08-28T04:10:02.881Z",
  "data": {
    "total": 61,
    "buckets": [
      {
        "key": "apprentice",
        "label": "Apprentice",
        "total": 33,
        "types": [
          {
            "key": "radical",
            "label": "Radicals",
            "total": 14,
            "items": [
              { "id": 1, "object": "radical",
                "data": { "slug": "ground", "level": 1, "characters": "一",
                          "meanings": [ { "meaning": "Ground", "primary": true } ] } }
            ]
          },
          { "key": "kanji", "label": "Kanji", "total": 11, "items": [ … ] },
          { "key": "vocabulary", "label": "Vocabulary", "total": 8, "items": [ … ] }
        ]
      },
      { "key": "guru", "label": "Guru", "total": 18, "types": [ … ] },
      { "key": "master", "label": "Master", "total": 7, "types": [ … ] },
      { "key": "enlightened", "label": "Enlightened", "total": 0, "types": [ … ] },
      { "key": "burned", "label": "Burned", "total": 3, "types": [ … ] }
    ]
  }
}

• All five buckets are always present in SRS order, and each carries all three type groups, empty ones included. A client can draw a row for every stage without checking whether it exists.
• Items are trimmed to what a chip needs — slug, level, characters, meanings. No mnemonics, no context sentences.
• Ordered by level, then subject id, within each group.
• kana_vocabulary is folded into the vocabulary group, but each item keeps its real object.
• Stage 0 — unlocked but never studied, i.e. your pending lessons — is excluded, as are hidden assignments. The totals therefore agree exactly with item_spread on /dashboard; a test pins that.

Pacing

GET /lesson_allowance · App-specific

How many lessons today’s ceiling still permits. Exists so a client can honour max_daily_lessons without running the whole dashboard aggregation to learn one number.

{
  "object": "report",
  "url": "https://kanjibuddy.mblrc.me/api/v1/lesson_allowance",
  "data_updated_at": "2026-08-28T04:10:02.881Z",
  "data": {
    "max": 15,
    "started_today": 3,
    "remaining": 12
  }
}

• A lesson is an assignment gaining a started_at, and “today” is a calendar day in the account’s timezone — not a rolling 24 hours.
• started_today counts every lesson started, including ones begun through the picker, which ignores the cap. So remaining can be 0 while started_today exceeds max.
• remaining is always a number. There is no “unlimited”: the setting’s ceiling of 100 is the least restrictive it gets.

Extra Study

GET /study · App-specific

What one mode currently holds — a pure read that starts nothing. kind is required and is one of recent_lessons, recent_mistakes, burned_items.

{
  "object": "report",
  "data": {
    "kind": "recent_lessons",
    "capped": false,
    "total_count": 24,
    "progress": { "remaining": 24, "total": 24 },
    "items": [
      { "assignmentId": 77, "subjectId": 441 },
      { "assignmentId": 80, "subjectId": 444 }
    ]
  }
}

items carries ids only — no subjects. Fetch them with /subjects?ids=…. capped: true means the 100-item ceiling trimmed the set, so a client can say so rather than quietly showing a hundred of many more.

POST /study · App-specific

Two jobs at one address. Sending only kind opens or resumes a cycle; adding assignment_id records one item finished within it.

# open or resume — responds with the same shape as GET /study
-d '{ "kind": "recent_lessons" }'

# record one item done
-d '{ "kind": "recent_lessons", "assignment_id": 77 }'

{ "object": "report",
  "data": { "kind": "recent_lessons", "progress": { "remaining": 23, "total": 24 } } }

Resuming is the default — a cycle already in progress is returned as it stands, and only a finished one recycles. Recording is idempotent per item: the same assignment_id twice does not double-count. Note the request body is snake_case even though the response’s items are camelCase.

recent_mistakes does not count down because an item leaves that list by being answered correctly in a real review, not by being practised. Its number is simply how many mistakes you made in the last 24 hours.

Progression

GET /unlockable · App-specific

What POST /advance would open, and when each item would have opened on its own. Read-only, and the preview for the “unlock ahead of schedule” confirmation.

{
  "object": "report",
  "data": {
    "total": 2,
    "pending": 0,
    "blocked": null,
    "candidates": [
      {
        "subject_id": 440,
        "object": "kanji",
        "level": 1,
        "characters": "一",
        "slug": "一",
        "meanings": [{ "meaning": "One", "primary": true }],
        "unlocks_at": null
      },
      {
        "subject_id": 449,
        "object": "kanji",
        "level": 1,
        "characters": "大",
        "slug": "大",
        "meanings": [{ "meaning": "Big", "primary": true }],
        "unlocks_at": "2026-09-02T04:00:00.000Z"
      }
    ]
  }
}

Ordered soonest-first, with the unlocks_at: null items ahead of everything, then by level and id so the order is stable between calls. Render it in the order given: that ordering is the question the list answers, and regrouping by subject type throws it away.

The tranche is a snapshot. It is computed by the same findUnlockable that POST /advance acts on — one definition, asked two ways, so the list cannot promise something the button then declines to do — but it is recomputed on the POST, and a review finishing in between can change it.

blocked and pending

Both are app-specific and additive; candidates and total mean what they always meant. When blocked is set, candidates is empty and the POST would refuse for the same reason.

POST /advance · App-specific

Open the next tranche of lessons without waiting for the current ones to reach Guru — the “unlock ahead of schedule” button. The body is optional: send none and it opens the whole tranche, which is what it did before it could be narrowed.

-d '{ "subject_ids": [440, 449] }'

Ids that are not in the tranche are ignored rather than rejected. The list from GET /unlockable is a snapshot, and between drawing it and pressing the button an item can have been unlocked by a review finishing — failing the whole request over a stale id would turn a race into an error.

Omitting it is not the same request as listing every id. Omitting means “whatever the tranche holds when this arrives”, so it picks up anything that qualified in the meantime; listing means “exactly these”. The first is right for a plain “open the next tranche” button, the second for a selection someone built — which should never unlock an item they were not shown.

{
  "object": "report",
  "data": {
    "outcome": "unlocked",
    "unlocked": 12,
    "level": 2,
    "pending": 0,
    "reason": null
  }
}

Branch on outcome and reason, not on the message — these are the stable machine-readable values, and each maps to a different sentence in the UI.

POST, never GET, and deliberately: this is reachable from a bookmark, and a link prefetcher must not be able to advance someone’s progression without them clicking. Do not add a GET to this route — the read lives at GET /unlockable, which is a separate route precisely so that this one can stay write-only.

Burn Manager

POST /burn_manager · App-specific

Burning is the only one-way door in the SRS: an item leaves the review cycle and never returns. This is the way back through it, and the way back out again. Neither action exists in WaniKani’s API — resurrecting is a button on its item pages and retiring is a community userscript — so this is app-specific in full.

POST /burn_manager
{ "action": "resurrect", "subject_ids": [440, 449] }

{
  "object": "report",
  "data": {
    "action": "resurrect",
    "changed": [440],
    "skipped": [{ "subject_id": 449, "reason": "not_burned" }]
  }
}

What each action does

Check the state before acting, or report what you skipped. The userscript this borrows from does neither — its author says it “does not check whether items are actually burned before resurrecting them”, so a bulk action over a filter reset live items to Apprentice with no undo. The server here refuses per item; make sure your UI shows the skipped list rather than reporting the count you asked for.

Devices

POST /push_tokens · App-specific

Register this install for push notifications, or re-arm one that was retired. Authenticated as the user, because a push token only means anything attached to an account. See Push notifications.

-d '{ "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]", "platform": "ios" }'

{ "object": "push_token",
  "data": {
    "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
    "platform": "ios",
    "registered_at": "2026-08-21T18:26:31.004Z"
  } }

Expo tokens only. The format is validated on the way in so a typo fails at registration rather than silently never delivering. A bare APNs or FCM token is a 422. It upserts, so calling it on every launch is correct and cheap — that is also how a token retired after delivery failures gets re-armed.

DELETE /push_tokens · App-specific

Stop pushing to this install. Same body as POST, responds { "object": "push_token", "data": { "removed": 1 } }.

Idempotent — unregistering twice reports removed: 0 and is not an error. Scoped to your own tokens, so one account cannot unregister another’s device by guessing.

Internal endpoints

/internal/* and /unsubscribe are service-to-service, guarded by a shared secret or a signed token, and will not accept your bearer. They are listed on the overview only so you know to leave them alone.