
β οΈ Disclaimer
- This API does not store any media files; it only links to content hosted by 3rdβparty services.
- This API is built for educational purposes only and not for commercial use.
- The maintainers of this repository are not responsible for any misuse.
β¨ Features
- Home info β spotlights, trending lists, topβten, schedule and category previews
- Anime info β seasons, related shows, recommendations, characters and sidebar βQtipβ data
- Episodes & streaming β episode lists, available servers, primary + fallback streaming info
- Search & filter β keyword search, advanced filter options, suggestions and top search keywords
- People & studios β character details, voice actors, producer and studio catalogues
- Schedule & random β daily schedule plus nextβepisode info and random anime endpoints
- Caching & observability β perβroute TTLs backed by Redis (optional) and Zap structured logs
All public HTTP routes are documented via Swagger and kept in sync with the codebase.
π§± Tech Stack
| Component |
Technology |
Purpose |
| Language |
Go 1.25 |
Highβperformance backend runtime |
| Framework |
Fiber v2 |
Fast HTTP framework with minimal overhead |
| Cache |
Redis |
Optional response caching per endpoint |
| Logger |
Zap |
Structured JSON/console logging |
| Config |
Viper |
Configuration and .env loading |
| Docs |
Swag + UI |
Swagger/OpenAPI generation and UI integration |
π Quick Start
Prerequisites
- Go 1.21 or higher
- Redis 6.0+ (optional, for caching)
- Docker & Docker Compose (optional, for containerized setup)
Installation
1. Clone the Repository
git clone https://github.com/mnuddindev/jutsu-api.git
cd jutsu-api
2. Install Dependencies
make install
# or
go mod download
cp env.example .env
# Edit .env with your configuration
4. Start Services (Docker)
make docker-up
# or
docker-compose up -d
5. Run the Application
make run
# or
go run cmd/api/main.go
The API will be available at http://localhost:8080
βοΈ Configuration
Configuration is managed through environment variables. Key settings:
# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
# Logger
LOG_LEVEL=info
LOG_ENCODING=console
See env.example for all available options.
π§ͺ Testing
Run all tests:
make test
# or
go test ./...
Run tests with coverage:
make test-coverage
Run linting:
make lint
# or
golangci-lint run ./...
π³ Docker
Using Docker Compose
# Start all services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
Build Docker Image
docker build -t jutsu-api .
docker run -p 8080:8080 jutsu-api
π Documentation
The HTTP interface is fully described via Swagger:
- UI:
http://localhost:8080/docs
- Files:
docs/swagger.json, docs/swagger.yaml, docs/docs.go
GET Home info
GET /api/
Endpoint
/api/
No parameter required β
Example of request
curl -X GET "http://localhost:8080/api/"
Sample Response
{
"success": true,
"results": {
"spotlights": [
{
"id": "string",
"data_id": "string",
"title": "Frieren: Beyond Journey's End",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"description": "string",
"tvInfo": {
"showType": "string",
"duration": "string",
"releaseDate": "string",
"quality": "string",
"episodeInfo": [
{}
]
}
}
],
"trending": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
],
"topTen": {
"today": [
{
"id": "string",
"data_id": "string",
"number": 0,
"name": "string",
"poster": "https://example.com/poster.jpg",
"tvInfo": {}
}
],
"week": [
{
"id": "string",
"data_id": "string",
"number": 0,
"name": "string",
"poster": "https://example.com/poster.jpg",
"tvInfo": {}
}
],
"month": [
{
"id": "string",
"data_id": "string",
"number": 0,
"name": "string",
"poster": "https://example.com/poster.jpg",
"tvInfo": {}
}
]
},
"today": {
"schedule": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"releaseDate": "string",
"time": "string",
"episode_no": 0
}
]
},
"genres": [
"string"
]
}
}
GET Top 10 anime's info
GET /api/top-ten
Endpoint
/api/top-ten
No parameter required β
Example of request
curl -X GET "http://localhost:8080/api/top-ten"
Sample Response
{
"success": true,
"results": {
"today": [
{
"id": "string",
"data_id": "string",
"number": 0,
"name": "string",
"poster": "https://example.com/poster.jpg",
"tvInfo": {}
}
],
"week": [
{
"id": "string",
"data_id": "string",
"number": 0,
"name": "string",
"poster": "https://example.com/poster.jpg",
"tvInfo": {}
}
],
"month": [
{
"id": "string",
"data_id": "string",
"number": 0,
"name": "string",
"poster": "https://example.com/poster.jpg",
"tvInfo": {}
}
]
}
}
GET Top Search
GET /api/top-search
Endpoint
/api/top-search
No parameter required β
Example of request
curl -X GET "http://localhost:8080/api/top-search"
Sample Response
{
"success": true,
"results": [
{
"title": "string",
"link": "string"
}
]
}
GET Specified anime's info
GET /api/info
Endpoint
/api/info?id={string}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
id |
query |
string |
anime-id |
Yes βοΈ |
-- |
Example of request
curl -X GET "http://localhost:8080/api/info?id=frieren-beyond-journeys-end-18542"
Sample Response
{
"success": true,
"results": {
"data": {
"id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"description": "string",
"stats": {},
"genres": [
"string"
]
},
"seasons": [
{}
],
"relatedAnime": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
],
"recommended": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
]
}
}
GET Random anime's info
GET /api/random
Endpoint
/api/random
No parameter required β
Example of request
curl -X GET "http://localhost:8080/api/random"
Sample Response
{
"success": true,
"results": {
"data": {
"id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"description": "string",
"stats": {},
"genres": [
"string"
]
},
"seasons": [
{}
],
"relatedAnime": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
],
"recommended": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
]
}
}
GET Categories info
GET /api/{category}
Endpoint
/api/{category}?page={number}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
category |
path |
string |
Category |
Yes βοΈ |
-- |
page |
query |
number |
Page-no. |
No β |
1 |
Available Categories
π Status & Popularity Filters
top-airing
most-popular
most-favorite
completed
recently-updated
recently-added
top-upcoming
π£οΈ Language Filters
subbed-anime
dubbed-anime
π Genre Filters
genre/action
genre/adventure
genre/cars
genre/comedy
genre/dementia
genre/demons
genre/drama
genre/ecchi
genre/fantasy
genre/game
genre/harem
genre/historical
genre/horror
genre/isekai
genre/josei
genre/kids
genre/magic
genre/martial-arts
genre/mecha
genre/military
genre/music
genre/mystery
genre/parody
genre/police
genre/psychological
genre/romance
genre/samurai
genre/school
genre/sci-fi
genre/seinen
genre/shoujo
genre/shoujo-ai
genre/shounen
genre/shounen-ai
genre/slice-of-life
genre/space
genre/sports
genre/super-power
genre/supernatural
genre/thriller
genre/vampire
π Alphabetical (A-Z) Listing
az-list
az-list/other
az-list/0-9
az-list/a
az-list/b
az-list/c
az-list/d
az-list/e
az-list/f
az-list/g
az-list/h
az-list/i
az-list/j
az-list/k
az-list/l
az-list/m
az-list/n
az-list/o
az-list/p
az-list/q
az-list/r
az-list/s
az-list/t
az-list/u
az-list/v
az-list/w
az-list/x
az-list/y
az-list/z
movie
special
ova
ona
tv
music
Example of request
curl -X GET "http://localhost:8080/api/most-popular?page=1"
Sample Response
{
"success": true,
"results": {
"data": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
],
"totalPages": 0
}
}
GET Anime of specific producers or studio
GET /api/producer/{id}
Endpoint
/api/producer/{id}?page={number}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
id |
path |
string |
Producer ID |
Yes βοΈ |
-- |
page |
query |
number |
Page-no. |
No β |
1 |
Example of request
curl -X GET "http://localhost:8080/api/producer/1?page=1"
Sample Response
{
"success": true,
"results": {
"data": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
],
"totalPages": 0
}
}
GET Search result's info
GET /api/search
Endpoint
/api/search?keyword={string}&page={number}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
keyword |
query |
string |
keyword |
No β |
-- |
page |
query |
number |
Page-no. |
No β |
1 |
Example of request
curl -X GET "http://localhost:8080/api/search?keyword=one%20punch%20man&page=1"
Sample Response
{
"success": true,
"results": {
"data": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
],
"totalPage": 0,
"page": 0,
"hasNext": true
}
}
GET Search suggestions
GET /api/search/suggest
Endpoint
/api/search/suggest?keyword={string}
Parameters
| Parameter |
Parameter-Type |
Type |
Description |
Mandatory ? |
Default |
keyword |
query |
string |
keyword |
Yes βοΈ |
-- |
Example of request
curl -X GET "http://localhost:8080/api/search/suggest?keyword=demon"
Sample Response
{
"success": true,
"results": [
{
"title": "string",
"link": "string"
}
]
}
GET Filter Anime
GET /api/filter
Endpoint
/api/filter?keyword={string}&type={string}&status={string}&rated={string}&score={string}&season={string}&language={string}&genres={string}&sort={string}&sy={string}&sm={string}&sd={string}&ey={string}&em={string}&ed={string}&page={number}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
keyword |
query |
string |
Search keyword |
No β |
undefined |
type |
query |
string |
Type of anime (e.g., tv, movie, ova, ona, special) |
No β |
ALL |
status |
query |
string |
Status of anime (e.g., ongoing, completed) |
No β |
ALL |
rated |
query |
string |
Rating of anime |
No β |
ALL |
score |
query |
string |
Score rating |
No β |
ALL |
season |
query |
string |
Season of anime |
No β |
ALL |
language |
query |
string |
Language of anime (e.g., sub, dub) |
No β |
ALL |
genres |
query |
string |
Comma-separated list of genre IDs |
No β |
ALL |
sort |
query |
string |
Sorting method |
No β |
DEFAULT |
sy |
query |
string |
Start year |
No β |
undefined |
sm |
query |
string |
Start month |
No β |
undefined |
sd |
query |
string |
Start day |
No β |
undefined |
ey |
query |
string |
End year |
No β |
undefined |
em |
query |
string |
End month |
No β |
undefined |
ed |
query |
string |
End day |
No β |
undefined |
page |
query |
number |
Page number for pagination |
No β |
1 |
Example of Request
curl -X GET "http://localhost:8080/api/filter?type=tv&status=completed&rated=5&sort=default&page=1"
Sample Response
{
"success": true,
"results": {
"data": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"poster": "https://example.com/poster.jpg",
"duration": "string",
"type": "string",
"rating": "string",
"episodes": {
"sub": 0,
"dub": 0
}
}
],
"totalPage": 0,
"page": 0,
"hasNext": true
}
}
GET Anime's episode list
GET /api/episodes/{id}
Endpoint
/api/episodes/{id}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
id |
path |
string |
anime-id |
Yes βοΈ |
-- |
Example of request
curl -X GET "http://localhost:8080/api/episodes/one-piece-100"
Sample Response
{
"success": true,
"results": {
"episodes": [
{
"number": 0,
"title": "string",
"episodeId": "string",
"isFiller": true
}
]
}
}
GET Schedule of upcoming anime
GET /api/schedule
Endpoint
/api/schedule?date={string}&tzOffset={number}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
date |
query |
string |
date |
No β |
today |
tzOffset |
query |
number |
timezone offset |
No β |
-330 |
Example of request
curl -X GET "http://localhost:8080/api/schedule?date=2024-09-23"
Sample Response
{
"success": true,
"results": [
{
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"releaseDate": "string",
"time": "string",
"episode_no": 0
}
]
}
GET Schedule of next episode of Anime
GET /api/schedule/{id}
Endpoint
/api/schedule/{id}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
id |
param |
string |
anime-id |
Yes βοΈ |
-- |
Example of request
curl -X GET "http://localhost:8080/api/schedule/one-piece-100"
Sample Response
{
"success": true,
"results": {
"nextEpisodeSchedule": {
"id": "string",
"data_id": "string",
"title": "string",
"japanese_title": "string",
"releaseDate": "string",
"time": "string",
"episode_no": 0
}
}
}
GET Qtip info
GET /api/qtip/{id}
Endpoint
/api/qtip/{id}
Parameters
| Parameter |
Data-Type |
Description |
Mandatory ? |
Default |
id |
string |
anime-id |
Yes βοΈ |
-- |
Example of request
curl -X GET "http://localhost:8080/api/qtip/frieren-beyond-journeys-end-18542"
Sample Response
{
"success": true,
"results": {}
}
GET Characters
GET /api/character/list/{id}
Endpoint
/api/character/list/{id}?page={number}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
id |
path |
string |
anime-id |
Yes βοΈ |
-- |
page |
query |
number |
Page-no. |
No β |
1 |
Example of request
curl -X GET "http://localhost:8080/api/character/list/one-piece-100?page=1"
Sample Response
{
"success": true,
"results": {
"currentPage": 0,
"totalPages": 0,
"data": [
{
"character": {
"id": "string",
"name": "string",
"poster": "string",
"cast": "string"
},
"voiceActors": [
{
"id": "string",
"name": "string",
"poster": "string"
}
]
}
]
}
}
GET Streaming info
GET /api/stream/{id}
Endpoint
/api/stream/{id}?ep={string}&server={string}&type={string}
Parameters
| Parameter |
Parameter-Type |
Type |
Mandatory ? |
Default |
id |
path |
string |
Yes βοΈ |
-- |
ep |
query |
string |
Yes βοΈ |
-- |
server |
query |
string |
No β |
hd-1 |
type |
query |
string |
No β |
sub |
Example of request
curl -X GET "http://localhost:8080/api/stream/frieren-beyond-journeys-end-18542?ep=107257&server=hd-1&type=sub"
Sample Response
{
"success": true,
"results": {
"streamingLink": [
{
"id": "string",
"type": "sub",
"link": {
"file": "https://example.com/stream.m3u8",
"type": "string"
},
"tracks": [
{}
],
"intro": {},
"outro": {},
"server": "string"
}
],
"servers": [
{
"type": "string",
"data_id": "string",
"server_id": "string",
"serverName": "string"
}
]
}
}
GET Fallback Streaming info
GET /api/stream/fallback/{id}
Endpoint
/api/stream/fallback/{id}?ep={string}&server={string}&type={string}
Parameters
| Parameter |
Parameter-Type |
Type |
Mandatory ? |
Default |
id |
path |
string |
Yes βοΈ |
-- |
ep |
query |
string |
Yes βοΈ |
-- |
server |
query |
string |
No β |
-- |
type |
query |
string |
No β |
-- |
Example of request
curl -X GET "http://localhost:8080/api/stream/fallback/frieren-beyond-journeys-end-18542?ep=107257&server=hd-1&type=sub"
Sample Response
{
"success": true,
"results": {
"streamingLink": [
{
"id": "string",
"type": "sub",
"link": {
"file": "https://example.com/stream.m3u8",
"type": "string"
},
"tracks": [
{}
],
"intro": {},
"outro": {},
"server": "string"
}
],
"servers": [
{
"type": "string",
"data_id": "string",
"server_id": "string",
"serverName": "string"
}
]
}
}
GET Available servers of anime
GET /api/servers
Endpoint
/api/servers?ep={string}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
ep |
query |
string |
episode ID |
Yes βοΈ |
-- |
Example of request
curl -X GET "http://localhost:8080/api/servers?ep=124260"
Sample Response
{
"success": true,
"results": [
{
"type": "string",
"data_id": "string",
"server_id": "string",
"serverName": "string"
}
]
}
GET Character Details
GET /api/character/{id}
Endpoint
/api/character/{id}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
id |
path |
string |
character-id |
Yes βοΈ |
-- |
Example of request
curl -X GET "http://localhost:8080/api/character/asta-340"
Sample Response
{
"success": true,
"results": {
"data": [
{
"id": "string",
"name": "string",
"japaneseName": "string",
"profile": "string",
"about": {
"description": "string",
"style": "string"
},
"voiceActors": [
{}
],
"animeography": [
{}
]
}
]
}
}
GET Voice Actor Details
GET /api/actors/{id}
Endpoint
/api/actors/{id}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
id |
path |
string |
voice-actor-id |
Yes βοΈ |
-- |
Example of request
curl -X GET "http://localhost:8080/api/actors/gakuto-kajiwara-534"
Sample Response
{
"success": true,
"results": {
"data": [
{
"id": "string",
"name": "string",
"japaneseName": "string",
"profile": "string",
"about": {
"description": "string",
"style": "string"
},
"roles": [
{}
]
}
]
}
}
GET User Watchlist
GET /api/watchlist/{userId}
Endpoint
/api/watchlist/{userId}
/api/watchlist/{userId}/{page}
Parameters
| Parameter |
Parameter-Type |
Data-Type |
Description |
Mandatory ? |
Default |
userId |
path |
string |
User ID |
Yes βοΈ |
-- |
page |
path |
integer |
Page number |
No β |
1 |
Example of request
curl -X GET "http://localhost:8080/api/watchlist/user123"
Sample Response
{
"success": true,
"results": {
"totalPages": 0,
"data": [
{
"id": "string",
"title": "string",
"poster": "string",
"type": "string",
"subCount": 0,
"dubCount": 0
}
]
}
}
GET Health Check
GET /health
Endpoint
/health
No parameter required β
Example of request
curl -X GET "http://localhost:8080/health"
Sample Response
{
"status": "ok",
"service": "Jutsu API",
"version": "1.0.0",
"uptime": "string",
"timestamp": "string",
"checks": {
"cache": {
"status": "string",
"response_time_ms": 0
},
"external_sources": {
"anime_provider": {}
}
}
}
π€ Contributing
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Development Guidelines
- Follow Go best practices and conventions
- Write tests for new features
- Update documentation
- Ensure all tests pass
- Run linter before submitting
π License
This project is licensed under the MIT License β see LICENSE for details.
π Acknowledgements
- Powered by the anime community
- Built with Go and Fiber
Made with Go and Fiber. If you find this useful, consider starring the repo. β