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:

{
  "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:

{
  "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):

{
  "domain": "https://wpengine.com/",
  "limit": 25
}

• Expected Response:

{
  "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:

{
  "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:

{
  "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

curl https://ubuntu593-alt-scraper-api.hf.space/health

Test 2: System Status

curl "https://ubuntu593-alt-scraper-api.hf.space/api/status?domain=https://wpengine.com/"

Test 3: Start Scan

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)

curl "https://ubuntu593-alt-scraper-api.hf.space/api/progress?job_id=PASTE_JOB_ID"

Test 5: Result (when status = done)

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!