📡 apiwatch — API Uptime Monitor + Telegram Alerts

---

❓ Problem

If you deploy your own APIs — on a VPS, a small cloud instance, wherever — you usually find out they're down the same way: a user complains, or you happen to check. Paid monitoring services solve this, but they're overkill (and a recurring cost) for a handful of personal or freelance-scale endpoints.

---

💡 Solution

A CLI tool that watches your endpoints and tells you the moment something breaks — no dashboard to babysit, no subscription:

• Register any number of endpoints, each on its own ping interval
• Concurrent monitoring — endpoints are checked independently, one slow/timing-out endpoint never blocks the others
• Real-time Telegram alerts — down and recovery notifications, sent to one or multiple recipients
• SLA reporting — uptime %, average response time, and a response-time trend, over any time window

---

✨ Features

• ➕ Endpoint Management — add / list / remove registered endpoints, stored in SQLite
• ⚡ Concurrent Monitoring Loop — thread-based scheduler, each endpoint pinged on its own interval without blocking others
• 🟢🔴 Up/Down Detection — classifies every check, tracks state transitions
• 📲 Telegram Alerts — instant down alerts and recovery alerts (with downtime duration), sent via a dedicated bot
• 👥 Multi-Recipient Support — alert more than one chat/person; one failed delivery doesn't block the others
• 📊 SLA Reports — uptime %, total checks, downtime count, average response time, longest down streak, over any --last window
• 📈 Response Time Trend — flags endpoints getting slower or faster over the report window, color-coded
• 🛡️ Fails Safe — a broken Telegram config or a failed alert never crashes the monitoring loop

---

🛠️ Tech Stack

Layer	Tool	Purpose
CLI Framework	Typer	Command parsing, options, help text
HTTP	Requests	Pinging endpoints, calling the Telegram Bot API
Concurrency	ThreadPoolExecutor	Independent per-endpoint scheduling (I/O-bound, thread-based)
Storage	SQLite	Endpoint registry + full check history
Alerts	Telegram Bot API	Down/recovery notifications
Config	python-dotenv	Bot token + chat ID(s) from .env, never hardcoded
Terminal UI	Rich	Color-coded tables for lists and reports
Testing	pytest	55 tests — storage, monitor, alerts, and report logic, all HTTP mocked

---

📡 Commands

Register and manage endpoints

apiwatch add --url "https://api.example.com/health" --interval 5m
apiwatch list
apiwatch remove --url "https://api.example.com/health"

--interval accepts s / m / h (e.g. 30s, 5m, 1h).

Start monitoring

apiwatch start

Runs until stopped with Ctrl+C. Pings every registered endpoint on its own schedule, prints live status, and sends Telegram alerts on every up→down or down→up transition (if Telegram is configured).

Get an SLA report

apiwatch report --last 7d
apiwatch report --last 24h

Shows, per endpoint: uptime %, total checks, down count, average response time, longest down streak, and a trend indicator.

---

📲 Telegram Setup

1. Message @BotFather on Telegram, send /newbot, follow the prompts — you'll get a bot token.
2. Message your new bot anything (e.g. "hi") so Telegram registers a chat with it.
3. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser — find "chat":{"id":...} in the response. That number is your chat ID.
4. Copy .env.example to .env and fill in:

TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_CHAT_ID=your-chat-id-here

For multiple recipients, use a comma-separated list:

TELEGRAM_CHAT_ID=123456789,987654321

If Telegram isn't configured, apiwatch start still monitors and prints to the terminal — alerts are simply skipped with a warning.

---

📁 Project Structure

apiwatch/
├── apiwatch/
│   ├── cli.py              # Typer app — add/list/remove/start/report
│   ├── monitor.py           # concurrent ping loop + state-change detection
│   ├── storage/               # SQLite: endpoint registry + check history
│   ├── alerts/                  # Telegram integration
│   ├── report.py                  # SLA calculation + trend detection
│   └── config.py                    # loads .env (bot token, chat IDs)
├── tests/                             # 55 tests
├── .env.example                        # template — copy to .env
└── pyproject.toml

---

⚡ Quick Start

git clone https://github.com/rizalcodes/apiwatch.git
cd apiwatch

python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

pip install -e .
cp .env.example .env   # then fill in your Telegram bot token + chat ID

apiwatch add --url "https://your-api.com/health" --interval 5m
apiwatch start

For development

pip install -e ".[dev]"
pytest

---

👤 Author

Rizal

---

Built with Typer, threading, and the Telegram Bot API — because finding out your API is down should never come from a client's message first.