GitHub Followers API

A powerful, secure REST API for automating GitHub follower management. Follow back new followers, farm followers from popular repositories, and cleanup non-followers - all through a simple API.

✨ Features

• Auto-Follow Back - Automatically follows users who follow you
• Smart Farming - Finds and follows active users from trending repos
• Scheduled Cleanup - Unfollows users who don't follow back
• Telegram Notifications - Get reports via Telegram (optional)
• API Key Protection - Secure your API with header-based authentication
• REST API - Control everything via HTTP endpoints

---

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

Copy the example environment file:

copy .env.example .env

Edit .env with your credentials:

APP_NAME=GitHub-Followers-API
APP_ENV=development
API_KEY=your_secret_api_key

GITHUB_TOKEN=your_github_token
TELEGRAM_BOT_TOKEN=your_telegram_bot_token  # Optional
TELEGRAM_CHAT_ID=your_chat_id               # Optional

Get your GitHub Token: GitHub Settings > Developer settings > Personal access tokens

3. Configure Bot (Optional)

Copy and edit config.example.json to config.json:

{
  "farming": {
    "enabled": true,
    "target_repos": ["torvalds/linux", "facebook/react"],
    "daily_follow_limit": 100
  },
  "cleanup_non_followers": true
}

4. Run the API

Option A: Double-click run_api.bat

Option B: Run manually:

uvicorn api:app --reload --host 0.0.0.0 --port 8000

The API will start at http://127.0.0.1:8000

---

📖 API Documentation

Interactive Docs

Access the Swagger UI: http://127.0.0.1:8000/docs

Authentication

Protected endpoints require the X-API-Key header:

curl -H "X-API-Key: your_api_key" http://127.0.0.1:8000/v1/start -X POST

Endpoints

Public Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/status	Get bot status and stats

Protected Endpoints (require X-API-Key)

Method	Endpoint	Description
GET	/v1/config	View current configuration
POST	/v1/start	Start background farming loop
POST	/v1/stop	Stop background farming loop
POST	/v1/follow-back	Trigger manual follow-back check
POST	/v1/cleanup	Trigger manual cleanup
POST	/v1/farm	Trigger one farming cycle

Example Responses

GET /health

{
  "status": "ok",
  "app_name": "GitHub-Followers-API",
  "environment": "development"
}

GET /status

{
  "status": "Stopped",
  "is_running": false,
  "authenticated_as": "your-username",
  "stats": {
    "followed_count": 150,
    "farming_stats": {
      "today": "2026-01-17",
      "follows_today": 25,
      "total_farmed": 500
    }
  }
}

POST /v1/start

{
  "message": "✅ Farming started in background",
  "success": true
}

---

🛡️ Security

• NEVER commit your .env file to GitHub
• All sensitive data uses os.getenv()
• API Key protection via X-API-Key header
• .gitignore excludes all secret files

If you suspect a token leak, revoke it immediately.

---

📁 Project Structure

.
├── api.py              # FastAPI application & endpoints
├── core.py             # Bot logic (follow, farm, cleanup)
├── requirements.txt    # Python dependencies
├── .env.example        # Environment template
├── config.example.json # Bot configuration template
├── run_api.bat         # Windows startup script
├── .gitignore          # Git exclusions
└── README.md           # This file

---

👤 Credits

Created by: dewhush

---

⚠️ Disclaimer: Use responsibly. GitHub has anti-spam policies. Aggressive settings may get your account flagged.