🎬 ScreenScape API

A powerful, modern API service for scraping movie and anime content from multiple providers

---

⭐ If you find this project useful, please consider giving it a star! ⭐

🌐 Live Demo • 📖 Documentation • 🐛 Report Bug • ✨ Request Feature

📋 Table of Contents

• Features
• Architecture
• Screenshots
• Supported Providers
• Tech Stack
• Getting Started
• API Documentation
• Authentication
• Environment Variables
• Deployment
• Contributing
• Performance & Optimization
• Roadmap
• License
• Support
• Star History

✨ Features

Core Features

• 🔐 Secure API Key Authentication - JWT-based authentication with request quota management
• 📊 Multiple Content Providers - Support for 15+ providers including KMMovies, AnimeSalt, NetMirror, and more
• 🎯 Comprehensive Endpoints - Search, details, streaming links, and download options
• 🚀 High Performance - Built with Next.js 16 and modern optimizations with edge caching
• 📱 Modern Dashboard - User-friendly interface for API key management and documentation

Advanced Features

• 🔄 Real-time Updates - Dynamic content scraping with intelligent caching strategies
• 📖 Interactive Documentation - Built-in API playground with TypeScript/JavaScript examples
• 🎨 Beautiful UI - Shadcn/ui components with Tailwind CSS and dark mode support
• 💾 PostgreSQL Database - Powered by Neon serverless PostgreSQL with Drizzle ORM
• 📧 Email Notifications - Automated login alerts and quota warnings with beautiful HTML emails
• 🔒 Rate Limiting - Intelligent quota management at both user and API key levels
• 📈 Usage Analytics - Track your API usage with detailed statistics
• 🌐 Cross-Platform - Works seamlessly on mobile, desktop, and tablets
• 🔍 Smart Search - Advanced search with filters and auto-suggestions
• 🎬 Multiple Extractors - Support for various video streaming platforms

� Architecture

System Architecture

graph TB
    subgraph Client["👤 Client Applications"]
        Web["🌐 Web Browser"]
        Mobile["📱 Mobile App"]
        API_Client["🔧 API Client"]
    end

    subgraph NextJS["⚡ Next.js App Router"]
        Pages["📄 Pages/Routes"]
        API["🔌 API Routes"]
        Auth["🔐 Authentication"]
    end

    subgraph Services["🛠 Services Layer"]
        Scrapers["🕷️ Web Scrapers"]
        Validators["✅ Validators"]
        Cache["💾 Cache Manager"]
        Email["📧 Email Service"]
    end

    subgraph Data["💽 Data Layer"]
        Neon[("🐘 Neon PostgreSQL")]
        Redis[("⚡ Upstash Redis")]
    end

    subgraph External["🌍 External Sources"]
        Providers["🎬 Content Providers"]
        Extractors["🎥 Video Extractors"]
    end

    Client --> NextJS
    NextJS --> Services
    Services --> Data
    Services --> External
    
    Auth --> Neon
    API --> Validators
    Validators --> Cache
    Cache --> Redis
    Scrapers --> Providers
    Scrapers --> Extractors

    style Client fill:#e1f5ff
    style NextJS fill:#fff3e0
    style Services fill:#f3e5f5
    style Data fill:#e8f5e9
    style External fill:#fce4ec

Loading

Authentication Flow

sequenceDiagram
    participant U as 👤 User
    participant C as 🌐 Client
    participant A as 🔐 Auth API
    participant DB as 💾 Database
    participant E as 📧 Email Service

    U->>C: Login Request
    C->>A: POST /api/auth/login
    A->>DB: Verify Credentials
    DB-->>A: User Data
    A->>DB: Create Session
    A->>E: Send Login Alert
    E-->>U: Email Notification
    A-->>C: Session Token
    C-->>U: Login Success

    Note over U,E: API Key Generation
    U->>C: Generate API Key
    C->>A: POST /api/keys
    A->>DB: Verify Session
    A->>DB: Create API Key
    DB-->>A: API Key Data
    A-->>C: API Key
    C-->>U: Display Key

Loading

API Request Flow

sequenceDiagram
    participant C as 👤 Client
    participant M as 🛡️ Middleware
    participant A as 🔌 API Handler
    participant V as ✅ Validator
    participant S as 🕷️ Scraper
    participant Ch as 💾 Cache
    participant P as 🌐 Provider

    C->>M: API Request + Key
    M->>V: Validate API Key
    V->>Ch: Check Request Quota
    
    alt Quota Exceeded
        V-->>C: 429 Quota Exceeded
    else Valid Request
        V->>Ch: Check Cache
        
        alt Cache Hit
            Ch-->>A: Cached Data
            A-->>C: Response
        else Cache Miss
            A->>S: Scrape Request
            S->>P: Fetch Content
            P-->>S: HTML Response
            S->>S: Parse Data
            S->>Ch: Store Cache
            S-->>A: Parsed Data
            A-->>C: Response
        end
        
        V->>V: Update Quota
    end

Loading

Database Schema

erDiagram
    USER ||--o{ API_KEY : has
    USER ||--o{ SESSION : has
    USER {
        string id PK
        string email
        string name
        int totalRequestCount
        int totalRequestQuota
        timestamp createdAt
        timestamp lastQuotaWarningAt
    }
    
    API_KEY {
        string id PK
        string key UK
        string userId FK
        string name
        int requestCount
        int requestQuota
        boolean isActive
        timestamp lastUsedAt
        timestamp createdAt
    }
    
    SESSION {
        string id PK
        string userId FK
        string token UK
        timestamp expiresAt
        timestamp createdAt
    }

Loading

📱 Screenshots

Mobile Application

Home Screen	Search & Discovery	Video Player	Content Details
Content Providers	Server Selection	Settings

Desktop Application

Desktop Dashboard
Video Player	Content Information
Episode Browser	Player Controls

�🎯 Supported Providers

Movies & TV Shows

• KMMovies - Latest Bollywood, Hollywood, and dubbed movies

  • Homepage listings with pagination
  • Advanced search functionality
  • Detailed movie information with IMDb ratings
  • Multiple quality download links (480p, 720p, 1080p, 4K)
  • Magic links resolver for direct downloads

• NetMirror - Streaming content with multiple servers

  • Homepage content with categories
  • Search functionality
  • Post details with metadata
  • Stream links with playlist URLs

Anime

• AnimeSalt - Comprehensive anime database
  • Latest anime releases
  • Episode listings
  • Streaming and download links
  • Search with filters

🛠 Tech Stack

Core Technologies

• Framework: Next.js 16 - React framework with App Router
• Language: TypeScript 5 - Type-safe JavaScript
• Runtime: Node.js 18+

Frontend

• Styling: Tailwind CSS 4 - Utility-first CSS framework
• UI Components: Shadcn/ui - Beautiful and accessible components
• Icons: Lucide React - Clean and consistent icons
• Animations: Framer Motion - Production-ready animations
• 3D Graphics: Three.js + React Three Fiber - 3D visualizations

Backend & Database

• Authentication: Better Auth - Modern auth library
• Database: Neon PostgreSQL - Serverless PostgreSQL
• ORM: Drizzle ORM - TypeScript ORM
• Caching: Upstash Redis - Serverless Redis

API & Scraping

• Web Scraping: Cheerio - Fast HTML parser
• HTTP Client: Axios - Promise-based HTTP client
• Validation: Zod - TypeScript-first schema validation
• API Validation: Custom middleware with quota management

Email & Communication

• Email Service: Resend - Modern email API
• Email Templates: React Email components

DevOps & Deployment

• Deployment: Vercel - Edge network deployment
• CI/CD: GitHub Actions
• Monitoring: Vercel Analytics
• Error Tracking: Built-in logging

🚀 Getting Started

Quick Start (3 minutes)

# 1. Clone and install
git clone https://github.com/Anshu78780/ScarperApi.git
cd ScarperApi
npm install

# 2. Setup environment
cp .env.example .env.local
# Edit .env.local with your credentials

# 3. Setup database
npm run db:push

# 4. Start development server
npm run dev

🎉 Visit http://localhost:3000

Detailed Setup

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18+ (Download)
• npm, yarn, pnpm, or bun package manager
• Git (Download)
• PostgreSQL Database (Neon recommended - free tier available)

1️⃣ Clone Repository

git clone https://github.com/Anshu78780/ScarperApi.git
cd ScarperApi

2️⃣ Install Dependencies

Choose your preferred package manager:

# Using npm
npm install

# Using yarn
yarn install

# Using pnpm
pnpm install

# Using bun
bun install

3️⃣ Environment Setup

Create environment file:

cp .env.example .env.local

Get your Neon database URL:

1. Sign up at Neon
2. Create a new project
3. Copy the connection string

Edit .env.local:

# Database (Required)
DATABASE_URL="postgresql://user:password@host/database?sslmode=require"

# Better Auth (Required)
BETTER_AUTH_SECRET="generate-a-random-secret-key"
BETTER_AUTH_URL="http://localhost:3000"

# Optional: Email Service (for notifications)
RESEND_API_KEY="your-resend-api-key"

# Optional: OAuth Providers
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

Generate a secure secret:

# Option 1: Using OpenSSL
openssl rand -base64 32

# Option 2: Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

4️⃣ Database Migrations

Run database migrations to create tables:

npm run db:push

This will create all necessary tables in your Neon database.

5️⃣ Start Development Server

npm run dev

The application will be available at:

• Frontend: http://localhost:3000
• API: http://localhost:3000/api

6️⃣ Create Your First Account

1. Navigate to http://localhost:3000/signup
2. Create an account
3. Log in at http://localhost:3000/login
4. Go to Dashboard → APIs to generate your first API key
5. Start making requests! 🎉

Development Commands

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run database migrations
npm run db:push

# Generate database migrations
npm run db:generate

# Open Drizzle Studio (Database GUI)
npm run db:studio

# Lint code
npm run lint

📚 API Documentation

Access the interactive API documentation at /dashboard/docs after logging in.

Quick API Usage

JavaScript/TypeScript

// Using fetch
const response = await fetch('https://screenscapeapi.dev/api/kmmovies/search?q=inception', {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Python

import requests

url = "https://screenscapeapi.dev/api/kmmovies/search"
params = {"q": "inception"}
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
data = response.json()
print(data)

cURL

curl -X GET "https://screenscapeapi.dev/api/kmmovies/search?q=inception" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Node.js (Axios)

const axios = require('axios');

axios.get('https://screenscapeapi.dev/api/kmmovies/search', {
  params: { q: 'inception' },
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Available Endpoints

KMMovies

• GET /api/kmmovies - Latest releases
• GET /api/kmmovies/search?q={query} - Search movies
• GET /api/kmmovies/details?url={url} - Movie details
• GET /api/kmmovies/magiclinks?url={url} - Download links

AnimeSalt

• GET /api/animesalt - Latest anime
• GET /api/animesalt/search?q={query} - Search anime
• GET /api/animesalt/details?url={url} - Anime details
• GET /api/animesalt/stream?url={url} - Streaming links

NetMirror

• GET /api/netmirror - Homepage content
• GET /api/netmirror/search?q={query} - Search content
• GET /api/netmirror/getpost?id={id} - Post details
• GET /api/netmirror/stream?id={id} - Stream URLs

🔐 Authentication

All API endpoints require authentication via API keys.

Getting an API Key

1. Sign up at /signup
2. Log in at /login
3. Navigate to /dashboard/apis
4. Generate a new API key
5. Copy and use in your requests

Authentication Methods

Header (Recommended)

curl -H "x-api-key: YOUR_API_KEY" https://screenscapeapi.dev/api/kmmovies

Query Parameter

curl "https://screenscapeapi.dev/api/kmmovies?api_key=YOUR_API_KEY"

Session (Dashboard) Automatic when logged into the dashboard

🔧 Environment Variables

Create a .env.local file in the project root with the following variables:

Required Variables

# Database Configuration (Required)
# Get from: https://neon.tech/
DATABASE_URL="postgresql://user:password@ep-xxx.us-east-2.aws.neon.tech/dbname?sslmode=require"

# Better Auth Configuration (Required)
# Generate a random 32-byte base64 string
BETTER_AUTH_SECRET="your-secret-key-min-32-characters"

# Application URL (Required)
# Development: http://localhost:3000
# Production: https://your-domain.com
BETTER_AUTH_URL="http://localhost:3000"

Optional Variables

# Email Service (Optional - for notifications)
# Get from: https://resend.com/
RESEND_API_KEY="re_xxxxxxxxxxxxx"
RESEND_FROM_EMAIL="noreply@yourdomain.com"

# OAuth Providers (Optional)
# GitHub OAuth - Get from: https://github.com/settings/developers
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

# Google OAuth (Optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Rate Limiting (Optional - defaults shown)
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=900000  # 15 minutes in milliseconds

# Cookie Management (Optional)
COOKIES_URL="https://your-cookies-endpoint.com/cookies.json"

# Application Settings (Optional)
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_APP_NAME="ScreenScape API"

# Redis Cache (Optional - for enhanced caching)
UPSTASH_REDIS_REST_URL="https://xxx.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your-token"

Environment Setup Guide

🔑 How to get DATABASE_URL (Neon PostgreSQL)

1. Go to Neon
2. Sign up for a free account
3. Create a new project
4. Navigate to your project dashboard
5. Copy the connection string from the dashboard
6. It should look like: postgresql://user:password@ep-xxx.region.aws.neon.tech/dbname?sslmode=require

🔐 How to generate BETTER_AUTH_SECRET

Use one of these methods to generate a secure random secret:

Option 1: OpenSSL (Linux/Mac)

openssl rand -base64 32

Option 2: Node.js

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Option 3: Online Generator Visit Generate Random and generate a 32+ character key

📧 How to get RESEND_API_KEY

1. Go to Resend
2. Sign up for a free account (100 emails/day free)
3. Navigate to API Keys section
4. Create a new API key
5. Copy the key (starts with re_)

🔗 How to get GitHub OAuth credentials

1. Go to GitHub Developer Settings
2. Click "New OAuth App"
3. Fill in the details:
   • Application name: Your app name
   • Homepage URL: http://localhost:3000 (dev) or your domain
   • Authorization callback URL: http://localhost:3000/api/auth/callback/github
4. Click "Register application"
5. Copy the Client ID
6. Generate a Client Secret and copy it

Example .env.local File

# Minimal setup for development
DATABASE_URL="postgresql://user:pass@host.neon.tech/db?sslmode=require"
BETTER_AUTH_SECRET="super-secret-key-at-least-32-characters-long"
BETTER_AUTH_URL="http://localhost:3000"

# Optional: Enable email notifications
RESEND_API_KEY="re_xxxxxxxxxxxxxxxxxx"

# Optional: Enable GitHub OAuth
GITHUB_CLIENT_ID="github_client_id_here"
GITHUB_CLIENT_SECRET="github_client_secret_here"

🌐 Deployment

Deploy on Vercel (Recommended)

Step-by-Step Vercel Deployment

1. Fork this repository

   # Click the Fork button on GitHub

2. Import to Vercel

   • Go to Vercel Dashboard
   • Click "Add New" -> "Project"
   • Import your forked repository

3. Configure Environment Variables Add the following in Vercel project settings:

   DATABASE_URL=your_neon_database_url
   BETTER_AUTH_SECRET=your_secret_key
   BETTER_AUTH_URL=https://your-domain.vercel.app

4. Deploy

   • Click "Deploy"
   • Wait for build to complete
   • Your API is live! 🎉

5. Run Database Migrations

   # After deployment, run migrations
   npm run db:push

Deploy on Render

Step-by-Step Render Deployment

1. Create New Web Service

   • Go to Render Dashboard
   • Click "New" -> "Web Service"
   • Connect your GitHub repository

2. Configure Build Settings

   Name: screenscape-api
   Environment: Node
   Build Command: npm install && npm run build
   Start Command: npm start

3. Add Environment Variables

   DATABASE_URL=your_neon_database_url
   BETTER_AUTH_SECRET=your_secret_key
   BETTER_AUTH_URL=https://your-app.onrender.com
   NODE_VERSION=18

4. Deploy

   • Click "Create Web Service"
   • Render will automatically build and deploy
   • Access your API at https://your-app.onrender.com

Deploy on Railway

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Initialize project
railway init

# Add environment variables
railway variables set DATABASE_URL="your_database_url"
railway variables set BETTER_AUTH_SECRET="your_secret"

# Deploy
railway up

Docker Deployment

# Create Dockerfile in project root
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

# Build and run
docker build -t screenscape-api .
docker run -p 3000:3000 --env-file .env screenscape-api

Manual Deployment

# Clone repository
git clone https://github.com/Anshu78780/ScarperApi.git
cd ScarperApi

# Install dependencies
npm install

# Build application
npm run build

# Start production server
npm start

🚀 Performance & Optimization

Caching Strategy

• Provider Cache: 30-minute TTL for content listings
• Search Results: 15-minute TTL
• Video Links: 5-minute TTL
• Static Assets: CDN caching with Vercel Edge Network

Performance Metrics

• API Response Time: < 200ms (cached)
• First Contentful Paint: < 1.5s
• Time to Interactive: < 3s
• Lighthouse Score: 95+

Optimization Features

• Edge caching for API responses
• Database connection pooling
• Lazy loading for images
• Code splitting for faster page loads
• Gzip compression
• Serverless functions for scalability

🗪author️ Roadmap

✅ Completed

• Basic scraping functionality
• User authentication system
• API key management
• Quota system
• Email notifications
• Interactive documentation
• Mobile responsive design
• Dark mode support

🚧 In Progress

• GraphQL API support
• WebSocket for real-time updates
• Advanced analytics dashboard
• API versioning

🔮 Future Plans

• OAuth provider integration
• Webhook support
• Custom scraper plugins
• AI-powered content recommendations
• Multi-language support
• API playground improvements
• Rate limiting with Redis
• Monitoring and alerting
• API documentation generator
• SDK for popular languages (Python, Go, Ruby)

💡 Community Requests

Have an idea? Open an issue or start a discussion!

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

� Support

Get Help

• 💬 GitHub Discussions: Ask questions and share ideas
• 🐛 Issue Tracker: Report bugs
• 📧 Email: anshu78780@gmail.com
• 📖 Documentation: Read the docs

FAQ

How do I get an API key?

Sign up at the website, log in, and navigate to the dashboard to generate your API key.

What are the rate limits?

Free tier: 10,000 requests/month. Premium plans available with higher quotas.

Can I use this in production?

Yes! The API is production-ready. For commercial use, please review the license terms.

How do I report a bug?

Open an issue on GitHub with detailed information about the bug and steps to reproduce.

Security

Found a security vulnerability? Please email anshu78780@gmail.com instead of opening a public issue.

🚀 Star History

⭐ Star History Chart

🎆 Contributors & Stargazers

📊 Repository Stats

🙏 Acknowledgments

• Next.js
• Vercel
• Neon
• Shadcn/ui
• Better Auth

---

🚀 Built with passion by Anshu

If you found this project helpful, please consider giving it a ⭐ star!

_{Made with ❤️ and ☕}