Bunpro Sync

Sync your Bunpro grammar learning progress locally for analysis and insights.

⚠️ Important: This uses a community-documented API. The official Bunpro API Key from settings does NOT work - you need the Frontend API Token from your browser.

Overview

This skill fetches your Japanese grammar progress from Bunpro and stores it in a local SQLite database. Track SRS stages, review forecasts, JLPT progress, and identify grammar leeches (items that keep falling back).

API Keys: The Two Different Tokens

Bunpro has two different API tokens that serve different purposes:

❌ DO NOT USE: "Official" API Key (from Settings)

• Found at: bunpro.jp/settings/account
• Looks like: d406663ff421af27c87caaa62eefdb7a (32 hex characters)
• Does NOT work with the Frontend API endpoints this skill uses
• Returns 401 Unauthorized errors

✅ USE THIS: Frontend API Token (from Browser)

• Found in: Browser DevTools → Console or Application Storage
• Looks like: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... (long JWT, 200+ chars)
• This is what the skill requires
• Expires periodically (you'll need to refresh it)

How to Get the Frontend API Token

Method 1: Console (Recommended)

1. Go to bunpro.jp and log in
2. Press F12 to open DevTools
3. Click the Console tab
4. Paste this JavaScript and press Enter:

   Object.fromEntries(
     new URLSearchParams(
       document.cookie.replace(/; /g, '&')
     )
   ).frontend_api_token
   

5. Copy the long string that appears (starts with eyJ)

Method 2: Local Storage

1. Go to bunpro.jp and log in
2. Press F12 → Application tab (or Storage in Firefox)
3. In the left sidebar, expand Local Storage → https://bunpro.jp
4. Look for token, authToken, or frontend_api_token
5. Copy the value (starts with eyJ)

Method 3: Network Tab

1. Go to bunpro.jp and log in
2. Press F12 → Network tab
3. Refresh the page
4. Look for any API call (like /user or /queue)
5. Click it → Headers → Request Headers
6. Find Authorization: Bearer eyJ...
7. Copy the part after "Bearer "

⚠️ Token Expiry: The Frontend API Token expires eventually (days/weeks). When you get 401 errors, repeat the steps above to get a fresh token.

Quick Start

Sync All Data

# Using environment variable (recommended)
export BUNPRO_FRONTEND_API_TOKEN="eyJ0eXAiOiJKV1Qi..."
python3 scripts/sync.py

# Or pass token directly (less secure)
python3 scripts/sync.py --token "eyJ0eXAiOiJKV1Qi..."

# Store in specific directory
python3 scripts/sync.py --data-dir ~/bunpro-data

Sync Specific Data

# Only user info
python3 scripts/sync.py --user-only

# Only study queue
python3 scripts/sync.py --queue-only

# Only reviews
python3 scripts/sync.py --reviews-only

Force Full Sync

python3 scripts/sync.py --full

Database Schema

user

Your account info including level, XP, buncoin, lifetime status.

grammar_points

Grammar content including title, meaning, structure, JLPT level, unit/lesson.

reviews

Your SRS progress on each grammar point (stage, next review, burned status).

study_queue

Items scheduled for future review.

due_items

Items currently available for review (includes is_leech flag).

user_stats

Aggregated statistics (SRS overview, forecasts, JLPT progress, activity).

review_histories

Review session history (last session, last 24h).

sync_meta

Internal table tracking last sync timestamps.

Common Queries

-- Grammar mastery by JLPT level
SELECT jlpt_level, COUNT(*) as total,
       SUM(CASE WHEN burned = 1 THEN 1 ELSE 0 END) as burned
FROM reviews r
JOIN grammar_points g ON r.grammar_point_id = g.id
GROUP BY jlpt_level;

-- Upcoming reviews
SELECT DATE(next_review) as day, COUNT(*)
FROM reviews
WHERE next_review > datetime('now')
GROUP BY day
ORDER BY day
LIMIT 7;

-- Grammar leeches
SELECT g.title, g.meaning, d.streak, r.srs_stage_string
FROM due_items d
JOIN grammar_points g ON d.reviewable_id = g.id
LEFT JOIN reviews r ON d.reviewable_id = r.reviewable_id
WHERE d.is_leech = 1
ORDER BY d.streak ASC;

Query Tools

# Show SRS distribution
python3 scripts/queries.py srs

# Show upcoming review forecast
python3 scripts/queries.py forecast

# Show grammar mastery by JLPT level
python3 scripts/queries.py grammar --jlpt 5

# Show currently due reviews
python3 scripts/queries.py due

# Show grammar leeches
python3 scripts/queries.py leeches

# Show overall progress
python3 scripts/queries.py progress

# Show recent activity
python3 scripts/queries.py activity

API Notes

• Base URL: https://api.bunpro.jp/api/frontend
• Auth: Bearer JWT token from browser (not settings API key)
• Rate limits: Unknown - be reasonable
• Stability: Community-documented, may change without notice
• Permission: Reverse-engineered with permission from Bunpro team

Troubleshooting

401 Unauthorized:

• Token expired (get fresh one from browser)
• Using wrong token type (need Frontend API Token, not settings API key)
• Token format should be JWT (eyJ0eXAi...)

500 Server Error:

• Bunpro API may be down
• Endpoint may have changed
• Check Bunpro Community API docs

Empty data:

• You're in vacation mode (check bunpro.jp)
• No reviews done yet
• Different endpoint structure than expected

References

• Bunpro Community API GitHub
• Bunpro Community Forum API Discussion
• Postman Collection
• references/api-structure.md - Full endpoint documentation

Files

• scripts/sync.py - Main sync tool with CLI
• scripts/queries.py - Query helper with common reports
• references/api-structure.md - Bunpro API reference