A modern anime API
Base URL: https://kuroji-api-j4mh.onrender.com
# Check the home page
open https://kuroji-api-j4mh.onrender.com
# Check the docs
open https://kuroji-api-j4mh.onrender.com/docs
# GraphQL playground
open https://kuroji-api-j4mh.onrender.com/graphqlFast anime database API that pulls from multiple sources (AniList, Kitsu, Shikimori, TMDB, TVDB, MyAnimeList, Zerochan)
Important: You gotta index anime data before querying.
git clone https://github.com/daffineq/kuroji-api.git
cd kuroji-api
cp .env.example .env
# Edit .env with your config
docker compose up --build -dbun install
cp .env.example .env
# Edit .env with your config
bun run db:generate
bun run db:migrate
bun run dev # or bun run prodServer runs at http://localhost:3000
# Start indexing (delay in seconds between requests)
curl -X POST "http://localhost:3000/api/anime/indexer/start?delay=5"
# Stop it
curl -X POST "http://localhost:3000/api/anime/indexer/stop"
# Reset to page 1
curl -X POST "http://localhost:3000/api/anime/indexer/reset"Hit up the GraphQL playground at http://localhost:3000/graphql and play around with queries yourself.
Or check the REST docs at http://localhost:3000/docs
# Generate key (needs admin key)
curl -X POST "http://localhost:3000/api/api-key/generate" \
-H "x-api-key: YOUR_ADMIN_KEY"Database - Neon (Required)
- Sign up at Neon
- Free 500MB PostgreSQL
- Copy connection string
Redis - Upstash (Optional but recommended)
- Create account at Upstash
- Copy Redis URL
- Create account at Render
- New Web Service → Connect your repo
- Important: Set environment to
Dockerand Dockerfile path to./Dockerfile.render - Add your environment variables (check
.env.examplefor all options) - Deploy
Key env vars:
DATABASE_URL=your_neon_url
RENDER=true
ANIME_POPULARITY_THRESHOLD=7500
After deploy, start the indexer:
curl -X POST "https://your-app.onrender.com/api/anime/indexer/start?delay=5"Free tier heads up:
- Spins down after 15min inactivity, unless you set RENDER to true
- 512MB RAM - adjust
ANIME_POPULARITY_THRESHOLDaccordingly - Neon free tier = 500MB storage
Btw, the demo is being hosted using the same method as above!
Check .env.example - it's already documented with everything you need to know.
Memory Requirements:
- Recommended-Minimum: 200MB-500MB
- Recommended: 2GB-4GB
- Depends on your
ANIME_POPULARITY_THRESHOLDsetting
Kuroji keeps your data fresh automatically through a background scheduler. Here's what runs and when:
| Schedule | What it does |
|---|---|
| Every 30 minutes | Processes the update queue |
| Every hour | Queues recently aired anime for update |
| Every 6 hours | Queues anime airing today for update |
| Every 12 hours | Queues anime that aired 2 days ago for update |
| Schedule | What it does |
|---|---|
| Every 12 hours | Re-indexes all upcoming anime (NOT_YET_RELEASED) |
| Every other day | Re-indexes all currently airing anime (RELEASING) |
| Every other week | Full re-index of all anime in the database |
Re-indexing respects your
ANIME_POPULARITY_THRESHOLDsettings — upcoming anime usesANIME_POPULARITY_THRESHOLD_UPCOMINGspecifically. You can disable all re-indexing by settingANIME_REINDEXING_ENABLED=falsewhile keeping the update queue running. To disable the update queue entirely, setANIME_UPDATE_ENABLED=false. Set both tofalseto run Kuroji as a fully static database with no background updates.
# Dev
bun run dev # Hot reload
bun run prod # Production
# Database
bun run db:generate # Generate migrations
bun run db:migrate # Run migrations
bun run db:studio # Database GUI
bun run db:truncate # Clear data
bun run db:drop # Drop tablesYou can look at the visual anime schema at Schema
Kuroji API wouldn't be possible without the amazing data provided by these platforms
- AniList - Primary source for anime metadata and characters
- MyAnimeList - Additional metadata
- Zerochan - High-quality anime imagery and art
- Shikimori & Kitsu - Additional metadata
- TMDB & TVDB - Episodes and imagery
Fork it, branch it, commit it, push it, PR it.
MIT - do whatever you want
Made by daffineq