KumaDeck API v1

A small, read-only JSON API for your own tools: progress widgets, stats spreadsheets, browser extensions. Create a token in Settings → API and send it with every request:

curl -H "Authorization: Bearer kd_your_token" https://127.0.0.1:5080/api/v1/summary

Basics

Base URL: https://127.0.0.1:5080/api/v1. Everything is GET.
Responses use snake_case. Lists look like {"object":"collection","total":2,"data":[…]}.
Times are UTC, ISO 8601. Missing values are null.
Limit: 60 requests a minute per token. Over that you get 429; wait a minute.
A missing or revoked token gets 401.
Filters take comma-separated values, e.g. ?levels=1,2,3&types=kanji,vocabulary.

Endpoints

`GET /user`

Your level, plan, vacation status, time zone and study preferences.

`GET /summary`

What the dashboard shows: lessons_available, reviews_available, next_reviews_at, reviews_next_24_hours and stage_counts (sprout, sapling, tree, grove, forest).

`GET /subjects`

The course: radicals, kanji, vocabulary, grammar and conjugations, with meanings, readings, on_yomi, kun_yomi and component_subject_ids. Filters: levels, types (radical, kanji, vocabulary, grammar, conjugation), ids.

`GET /assignments`

Your progress per subject: stage (0 = lesson waiting, 1–4 Sprout, 5–6 Sapling, 7 Tree, 8 Grove, 9 Forest), stage_name, unlocked_at, started_at, passed_at, burned_at, available_at (next review), correct_count, incorrect_count. Filters: levels, types, ids (subject ids), stages.

`GET /study_materials`

Your own synonyms and notes: subject_id, meaning_synonyms, meaning_note, reading_note.

Example

GET /api/v1/assignments?stages=1,2,3,4&types=kanji

{
  "object": "collection",
  "total": 1,
  "data": [
    { "id": 812, "object": "assignment", "subject_id": 57, "subject_type": "kanji",
      "stage": 3, "stage_name": "Sprout 3", "available_at": "2026-11-10T14:00:00Z",
      "correct_count": 2, "incorrect_count": 1, ... }
  ]
}

Fair use

Keep your token secret: anyone with it can read your progress. Revoke it any time in Settings. Course text (mnemonics, grammar, stories) is for your personal use, not for republishing; dictionary data keeps its own licence (see Credits & licences).