POSTMAN_COLLECTION.md

# Postman Collection - Hugging Face Deployment
**Base URL**: `https://ubuntu593-alt-scraper-api.hf.space`

---

## 1️⃣ Health Check
**Simple uptime check**

- **Method**: `GET`
- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/health`
- **Expected Response**:
```json
{
  "status": "alive"
}
```

---

## 2️⃣ System Status
**Check server region, latency, and domain connectivity**

- **Method**: `GET`
- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/status?domain=https://wpengine.com/`
- **Parameters**:
  - `domain` (optional): Target domain to test connectivity
- **Expected Response**:
```json
{
  "region": "Frankfurt, DE",
  "latency": 45,
  "status": "operational",
  "engine": "AutoAlt Neural v2"
}
```

---

## 3️⃣ Start a New Scan
**Initiate async crawl job**

- **Method**: `POST`
- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/scanstart`
- **Headers**: 
  - `Content-Type: application/json`
- **Body** (raw JSON):
```json
{
  "domain": "https://wpengine.com/",
  "limit": 25
}
```
- **Expected Response**:
```json
{
  "job_id": "abc123-def456-..."
}
```
**⚠️ Save this `job_id` for the next steps!**

---

## 4️⃣ Check Scan Progress
**Poll for real-time updates**

### Option A: Path Parameter
- **Method**: `GET`
- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/progress/{job_id}`
  - Replace `{job_id}` with the actual ID from step 3

### Option B: Query Parameter (Easier for browser testing)
- **Method**: `GET`
- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/progress?job_id=YOUR_JOB_ID_HERE`

**Expected Response**:
```json
{
  "status": "running",
  "percent": 60,
  "pages_scanned": 15,
  "images_found": 87,
  "message": "Scanning: https://wpengine.com/about",
  "elapsed_seconds": 12,
  "eta_seconds": 8,
  "error": null
}
```

**Status Values**: `pending`, `running`, `done`, `error`

---

## 5️⃣ Get Final Results
**Retrieve complete JSON report (once status is `done`)**

### Option A: Path Parameter
- **Method**: `GET`
- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/result/{job_id}`

### Option B: Query Parameter
- **Method**: `GET`
- **URL**: `https://ubuntu593-alt-scraper-api.hf.space/api/result?job_id=YOUR_JOB_ID_HERE`

**Expected Response**:
```json
{
  "summary": {
    "total_pages_scanned": 25,
    "total_images_found": 145,
    "total_images_missing_alt": 23,
    "total_images_poor_quality": 5,
    "total_pages_discovered": 50,
    "blocked_reason": null,
    "crawl_blocked": false
  },
  "details": [ ... ]
}
```

---

## 🧪 Complete Test Flow (Copy to Postman)

### Test 1: Health Check
```bash
curl https://ubuntu593-alt-scraper-api.hf.space/health
```

### Test 2: System Status
```bash
curl "https://ubuntu593-alt-scraper-api.hf.space/api/status?domain=https://wpengine.com/"
```

### Test 3: Start Scan
```bash
curl -X POST "https://ubuntu593-alt-scraper-api.hf.space/api/scanstart" \
  -H "Content-Type: application/json" \
  -d '{"domain": "https://wpengine.com/", "limit": 25}'
```

### Test 4: Progress (use job_id from Test 3)
```bash
curl "https://ubuntu593-alt-scraper-api.hf.space/api/progress?job_id=PASTE_JOB_ID"
```

### Test 5: Result (when status = done)
```bash
curl "https://ubuntu593-alt-scraper-api.hf.space/api/result?job_id=PASTE_JOB_ID"
```

---

## ⚠️ Common Mistakes to Avoid

1. **Don't use `limit` parameter on `/api/status`** ❌
   - ❌ Wrong: `/api/status?domain=...&limit=25`
   - ✅ Right: `/api/status?domain=...`

2. **Use POST (not GET) for `/api/scanstart`** ❌
   - ❌ Wrong: GET request
   - ✅ Right: POST with JSON body

3. **Don't forget to URL-encode the domain parameter** ⚠️
   - If testing in browser, use `https%3A%2F%2Fwpengine.com%2F`
   - Postman/curl handle this automatically

---

## 🎯 Quick Postman Import

Create a new Postman collection and add these 5 requests with the URLs above. Test them in order!