jutsu-api

module
v0.0.0-...-c3a6988 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 11, 2025 License: MIT

README ΒΆ

Jutsu

πŸŒ€ Jutsu API

High-Performance Anime Streaming API built with Go

Go Version License Fiber Redis

A blazing-fast, production-ready RESTful API for anime streaming platforms

Features β€’ Quick Start β€’ Documentation β€’ API Reference β€’ Contributing

⚠️ Disclaimer

  1. This API does not store any media files; it only links to content hosted by 3rd‑party services.
  2. This API is built for educational purposes only and not for commercial use.
  3. 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
3. Configure Environment
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 /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
🎞️ Format/Type Filters
  • 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:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. 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. ⭐

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL