RESTful API Mode¶

Weeb CLI can run as a RESTful API server, providing HTTP endpoints for all provider operations including search, episode listing, stream extraction, and anime details.

Installation¶

Install with RESTful API dependencies:

pip install weeb-cli[serve-restful]

Usage¶

Basic Usage¶

Start the server with default settings:

weeb-cli serve restful

The server will start on http://0.0.0.0:8080 and automatically load all available providers.

Custom Configuration¶

weeb-cli serve restful \
  --port 9000 \
  --host 127.0.0.1 \
  --no-cors \
  --debug

All available providers are loaded automatically. Select which provider to use via the provider query parameter in API requests.

Command Options¶

Option	Environment Variable	Default	Description
`--port`	`RESTFUL_PORT`	`8080`	HTTP port to bind
`--host`	`RESTFUL_HOST`	`0.0.0.0`	Host address to bind
`--cors/--no-cors`	`RESTFUL_CORS`	`true`	Enable/disable CORS
`--debug`	`RESTFUL_DEBUG`	`false`	Enable debug mode

Note: All available providers are loaded automatically. Use the provider query parameter in API requests to select which provider to use.

API Endpoints¶

Health Check¶

Check if the server is running:

GET /health

Response:

{
  "status": "ok",
  "service": "weeb-cli-restful",
  "providers": ["animecix", "hianime", "aniworld", "docchi"]
}

List Providers¶

Get all available providers:

GET /api/providers

Response:

{
  "success": true,
  "providers": [
    {
      "name": "animecix",
      "lang": "tr",
      "region": "TR",
      "class": "AnimecixProvider"
    }
  ],
  "loaded": ["animecix", "hianime"]
}

Search Anime¶

Search for anime across providers:

GET /api/search?q=naruto&provider=animecix

Query Parameters: - q (required): Search query - provider (optional): Provider name (defaults to first loaded)

Response:

{
  "success": true,
  "provider": "animecix",
  "query": "naruto",
  "count": 10,
  "results": [
    {
      "id": "12345",
      "title": "Naruto",
      "type": "series",
      "cover": "https://example.com/cover.jpg",
      "year": 2002
    }
  ]
}

Get Anime Details¶

Get detailed information about an anime:

GET /api/anime/{anime_id}?provider=animecix

Query Parameters: - provider (optional): Provider name (defaults to first loaded)

Response:

{
  "success": true,
  "provider": "animecix",
  "anime": {
    "id": "12345",
    "title": "Naruto",
    "type": "series",
    "cover": "https://example.com/cover.jpg",
    "year": 2002,
    "description": "Anime description...",
    "genres": ["Action", "Adventure"],
    "status": "completed",
    "episodes": [...]
  }
}

Get Episodes¶

List all episodes for an anime:

GET /api/anime/{anime_id}/episodes?provider=animecix&season=1

Query Parameters: - provider (optional): Provider name (defaults to first loaded) - season (optional): Filter by season number

Response:

{
  "success": true,
  "provider": "animecix",
  "anime_id": "12345",
  "count": 220,
  "episodes": [
    {
      "id": "ep-1",
      "number": 1,
      "title": "Enter: Naruto Uzumaki!",
      "season": 1,
      "url": "https://example.com/episode/1"
    }
  ]
}

Get Streams¶

Get stream URLs for an episode:

GET /api/anime/{anime_id}/episodes/{episode_id}/streams?provider=animecix&sort=desc

Query Parameters: - provider (optional): Provider name (defaults to first loaded) - sort (optional): Sort by quality (asc or desc, defaults to desc)

Response:

{
  "success": true,
  "provider": "animecix",
  "anime_id": "12345",
  "episode_id": "ep-1",
  "count": 3,
  "streams": [
    {
      "url": "https://example.com/stream.m3u8",
      "quality": "1080p",
      "server": "default",
      "headers": {
        "Referer": "https://example.com"
      },
      "subtitles": null
    }
  ]
}

Docker Deployment¶

Using Docker Compose¶

docker-compose -f docker-compose.restful.yml up -d

Using Dockerfile¶

Build the image:

docker build -f Dockerfile.restful -t weeb-cli-restful .

Run the container:

docker run -d \
  --name weeb-cli-restful \
  -p 8080:8080 \
  weeb-cli-restful

Environment Variables¶

Configure the server via environment variables:

docker run -d \
  --name weeb-cli-restful \
  -p 9000:9000 \
  -e RESTFUL_PORT=9000 \
  -e RESTFUL_HOST=0.0.0.0 \
  -e RESTFUL_CORS=true \
  -e RESTFUL_DEBUG=false \
  weeb-cli-restful

Error Handling¶

All endpoints return consistent error responses:

{
  "success": false,
  "error": "Error message description"
}

Common HTTP Status Codes: - 200: Success - 400: Bad request (missing/invalid parameters) - 404: Resource not found - 500: Internal server error

CORS Support¶

CORS is enabled by default, allowing requests from any origin. To disable:

weeb-cli serve restful --no-cors

Or via environment variable:

export RESTFUL_CORS=false

Example Usage¶

cURL¶

# Search anime
curl "http://localhost:8080/api/search?q=naruto&provider=animecix"

# Get episodes
curl "http://localhost:8080/api/anime/12345/episodes?season=1"

# Get streams
curl "http://localhost:8080/api/anime/12345/episodes/ep-1/streams?sort=desc"

Python¶

import requests

# Search anime
response = requests.get(
    "http://localhost:8080/api/search",
    params={"q": "naruto", "provider": "animecix"}
)
results = response.json()

# Get streams
response = requests.get(
    f"http://localhost:8080/api/anime/{anime_id}/episodes/{episode_id}/streams",
    params={"provider": "animecix", "sort": "desc"}
)
streams = response.json()

JavaScript¶

// Search anime
const response = await fetch(
  'http://localhost:8080/api/search?q=naruto&provider=animecix'
);
const data = await response.json();

// Get streams
const streamResponse = await fetch(
  `http://localhost:8080/api/anime/${animeId}/episodes/${episodeId}/streams?sort=desc`
);
const streams = await streamResponse.json();

Production Deployment¶

Reverse Proxy (Nginx)¶

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Systemd Service¶

Create /etc/systemd/system/weeb-cli-restful.service:

[Unit]
Description=Weeb CLI RESTful API
After=network.target

[Service]
Type=simple
User=weeb
WorkingDirectory=/opt/weeb-cli
Environment="RESTFUL_PORT=8080"
ExecStart=/usr/local/bin/weeb-cli serve restful
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable weeb-cli-restful
sudo systemctl start weeb-cli-restful

Security Considerations¶

Authentication: The API does not include built-in authentication. Use a reverse proxy (Nginx, Traefik) with authentication if exposing publicly.
Rate Limiting: Implement rate limiting at the reverse proxy level to prevent abuse.
HTTPS: Always use HTTPS in production. Configure SSL/TLS at the reverse proxy level.
Firewall: Restrict access to trusted IPs if possible.

Troubleshooting¶

Port Already in Use¶

# Check what's using the port
lsof -i :8080

# Use a different port
weeb-cli serve restful --port 9000

Provider Not Found¶

Ensure the provider name is correct and available:

# List available providers
weeb-cli api providers

# Use correct provider name in API request
curl "http://localhost:8080/api/search?q=naruto&provider=animecix"

CORS Issues¶

If experiencing CORS issues, ensure CORS is enabled:

weeb-cli serve restful --cors

RESTful API Mode¶

Installation¶

Usage¶

Basic Usage¶

Custom Configuration¶

Command Options¶

API Endpoints¶

Health Check¶

List Providers¶

Search Anime¶

Get Anime Details¶

Get Episodes¶

Get Streams¶

Docker Deployment¶

Using Docker Compose¶

Using Dockerfile¶

Environment Variables¶

Error Handling¶

CORS Support¶

Example Usage¶

cURL¶

Python¶

JavaScript¶

Production Deployment¶

Reverse Proxy (Nginx)¶

Systemd Service¶

Security Considerations¶

Troubleshooting¶

Port Already in Use¶

Provider Not Found¶

CORS Issues¶

See Also¶