Kuroji API v2

A modern anime API

---

Try It Out - Public Demo

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/graphql

---

What's This?

Fast anime database API that pulls from multiple sources (AniList, Kitsu, Shikimori, TMDB, TVDB, MyAnimeList, Zerochan). REST + GraphQL, rate limiting, API keys - the whole package.

Important: You gotta index anime data before querying.

---

Quick Start

Docker (Recommended)

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 -d

Manual Install

bun install
cp .env.example .env
# Edit .env with your config
bun run db:generate
bun run db:migrate
bun run dev  # or bun run prod

Server runs at http://localhost:3000

---

How to Use

1. Index Your Data

# 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"

2. Query Your Data

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

3. API Keys (Optional)

# Generate key (needs admin key)
curl -X POST "http://localhost:3000/api/api-key/generate" \
  -H "x-api-key: YOUR_ADMIN_KEY"

---

Free Hosting on Render

Prerequisites

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

Deploy

1. Create account at Render
2. New Web Service → Connect your repo
3. Important: Set environment to Docker and Dockerfile path to ./Dockerfile.render
4. Add your environment variables (check .env.example for all options)
5. 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_THRESHOLD accordingly
• Neon free tier = 500MB storage

Btw, the demo is being hosted using the same method as above!

---

Configuration

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_THRESHOLD setting

---

Scripts

# 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 tables

---

Tech Stack

• Elysia
• Bun
• TypeScript
• Drizzle
• GraphQL Yoga
• Scalar

---

Database

You can look at the visual anime schema at Schema

---

Providers

Kuroji API wouldn't be possible without the amazing data provided by these platforms

Data Sources

• 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

---

Contributing

Fork it, branch it, commit it, push it, PR it.

---

License

MIT - do whatever you want

---

Made by daffineq

⭐ Star this if it's useful