README.md

---
title: Dev Altai API
emoji: ⚡
colorFrom: green
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# Dev Altai API (Alt Scraper)

A robust SEO scraping API built with FastAPI, Playwright, and advanced anti-bot bypass. Optimized for deployment on Hugging Face Spaces.

## 🚀 Quick Start

### Health Check
```
GET https://ubuntu593-dev-altai.hf.space/health
```

### Start a Scan
```
POST https://ubuntu593-dev-altai.hf.space/api/scanstart?domain=https://example.com&limit=25
```

Or with JSON body:
```bash
curl -X POST "https://ubuntu593-dev-altai.hf.space/api/scanstart" \
  -H "Content-Type: application/json" \
  -d '{"domain": "https://example.com", "limit": 25}'
```

**Response**: `{"job_id": "abc-123..."}`

### Check Progress
```
GET https://ubuntu593-dev-altai.hf.space/api/progress?job_id=YOUR_JOB_ID
```

### Get Results
```
GET https://ubuntu593-dev-altai.hf.space/api/result?job_id=YOUR_JOB_ID
```

## 📋 Complete API Reference

See [COMPLETE_API_REFERENCE.md](./COMPLETE_API_REFERENCE.md) for full documentation.

## 🔧 Features

- **Tiered Fetching Strategy**: curl_cffi → cloudscraper → Playwright
- **Anti-Bot Bypass**: Playwright Stealth mode with countermeasures
- **Real-time Progress**: WebSocket-like progress tracking
- **Async Processing**: Background job queue with FastAPI
- **Comprehensive Analysis**: Image ALT text, quality checks, and more

## 🛠️ Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | System health check |
| `/api/status` | GET | Server status & connectivity |
| `/api/scanstart` | POST | Start new scan job |
| `/api/progress` | GET | Check scan progress |
| `/api/result` | GET | Get scan results |

## 📦 Deployment

This app uses Docker and is configured for Hugging Face Spaces.

**Requirements**: 
- Python 3.10+
- Playwright browsers
- FastAPI + Uvicorn

See [Dockerfile](./Dockerfile) for deployment configuration.