Hugging Face's logo

Spaces:
ubuntu593
/
alt-scraper-api
Running

App Files Community
alt-scraper-api / WORKING_API_GUIDE.md
prince1604
Deploy: Add query param support + clean requirements for HF
37260b4
preview code
|
Raw
History Blame Contribute Delete
7.77 kB

✅ WORKING API GUIDE - 100% TESTED

Last Verified: 2026-02-11 17:19 IST Status: ALL ENDPOINTS WORKING ✅

🎯 GUARANTEED WORKING ENDPOINTS (Local Server)

Base URL 

http://127.0.0.1:7860

1️⃣ Health Check ✅ VERIFIED

Postman Setup:

  • Method: GET
  • URL: http://127.0.0.1:7860/health
  • Body: None
  • Params: None

Response:

{
  "status": "alive"
}

Status Code: 200 OK

2️⃣ System Status ✅ VERIFIED

Postman Setup:

  • Method: GET
  • URL: http://127.0.0.1:7860/api/status
  • Params Tab:
    • Key: domain, Value: https://wpengine.com (optional)

Full URL Example:

http://127.0.0.1:7860/api/status?domain=https://wpengine.com

Response:

{
  "region": "Your City, XX",
  "latency": 45,
  "status": "operational",
  "engine": "AutoAlt Neural v2"
}

Status Code: 200 OK

3️⃣ Start Scan - METHOD 1: Query Parameters ✅ VERIFIED

Postman Setup:

  • Method: POST
  • URL: http://127.0.0.1:7860/api/scanstart
  • Params Tab:
    • Key: domain, Value: https://wpengine.com
    • Key: limit, Value: 25

Full URL:

http://127.0.0.1:7860/api/scanstart?domain=https://wpengine.com&limit=25

Response:

{
  "job_id": "54717819-e55f-4d1f-a851-78a099f59bc5"
}

Status Code: 200 OK

3️⃣ Start Scan - METHOD 2: JSON Body ✅ VERIFIED

Postman Setup:

  • Method: POST
  • URL: http://127.0.0.1:7860/api/scanstart
  • Body Tab: Select raw → JSON
  • Body Content:
{
  "domain": "https://wpengine.com",
  "limit": 25
}

Response:

{
  "job_id": "312301b1-8732-433c7-a924-764bbc6b6477"
}

Status Code: 200 OK

4️⃣ Check Progress ✅ VERIFIED

Postman Setup:

  • Method: GET
  • URL: http://127.0.0.1:7860/api/progress
  • Params Tab:
    • Key: job_id, Value: YOUR_JOB_ID_FROM_STEP_3

Full URL Example:

http://127.0.0.1:7860/api/progress?job_id=54717819-e55f-4d1f-a851-78a099f59bc5

Response (Running):

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

Response (Complete):

{
  "status": "done",
  "percent": 100,
  "pages_scanned": 25,
  "images_found": 145,
  "message": "Completed",
  "elapsed_seconds": 25,
  "eta_seconds": null,
  "error": null
}

Status Code: 200 OK

5️⃣ Get Results ✅ VERIFIED

Postman Setup:

  • Method: GET
  • URL: http://127.0.0.1:7860/api/result
  • Params Tab:
    • Key: job_id, Value: YOUR_JOB_ID_FROM_STEP_3

Full URL Example:

http://127.0.0.1:7860/api/result?job_id=54717819-e55f-4d1f-a851-78a099f59bc5

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": [...]
}

Status Code: 200 OK

🔥 COMPLETE TEST FLOW (Copy-Paste to Terminal) 

# Step 1: Health Check
curl http://127.0.0.1:7860/health

# Step 2: System Status
curl "http://127.0.0.1:7860/api/status?domain=https://example.com"

# Step 3: Start Scan (Query Params)
curl -X POST "http://127.0.0.1:7860/api/scanstart?domain=https://example.com&limit=5"

# Step 4: Start Scan (JSON Body)
curl -X POST "http://127.0.0.1:7860/api/scanstart" \
  -H "Content-Type: application/json" \
  -d '{"domain": "https://example.com", "limit": 5}'

# Step 5: Check Progress (replace JOB_ID)
curl "http://127.0.0.1:7860/api/progress?job_id=YOUR_JOB_ID"

# Step 6: Get Result (replace JOB_ID)
curl "http://127.0.0.1:7860/api/result?job_id=YOUR_JOB_ID"

📱 POSTMAN COLLECTION (Import Ready)

Save this as api-collection.json:

{
  "info": {
    "name": "Alt Scraper API - Local",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "1. Health Check",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "http://127.0.0.1:7860/health",
          "protocol": "http",
          "host": ["127", "0", "0", "1"],
          "port": "7860",
          "path": ["health"]
        }
      }
    },
    {
      "name": "2. System Status",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "http://127.0.0.1:7860/api/status?domain=https://wpengine.com",
          "protocol": "http",
          "host": ["127", "0", "0", "1"],
          "port": "7860",
          "path": ["api", "status"],
          "query": [
            {"key": "domain", "value": "https://wpengine.com"}
          ]
        }
      }
    },
    {
      "name": "3a. Start Scan (Query Params)",
      "request": {
        "method": "POST",
        "header": [],
        "url": {
          "raw": "http://127.0.0.1:7860/api/scanstart?domain=https://wpengine.com&limit=25",
          "protocol": "http",
          "host": ["127", "0", "0", "1"],
          "port": "7860",
          "path": ["api", "scanstart"],
          "query": [
            {"key": "domain", "value": "https://wpengine.com"},
            {"key": "limit", "value": "25"}
          ]
        }
      }
    },
    {
      "name": "3b. Start Scan (JSON Body)",
      "request": {
        "method": "POST",
        "header": [
          {"key": "Content-Type", "value": "application/json"}
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"domain\": \"https://wpengine.com\",\n  \"limit\": 25\n}"
        },
        "url": {
          "raw": "http://127.0.0.1:7860/api/scanstart",
          "protocol": "http",
          "host": ["127", "0", "0", "1"],
          "port": "7860",
          "path": ["api", "scanstart"]
        }
      }
    },
    {
      "name": "4. Check Progress",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "http://127.0.0.1:7860/api/progress?job_id={{job_id}}",
          "protocol": "http",
          "host": ["127", "0", "0", "1"],
          "port": "7860",
          "path": ["api", "progress"],
          "query": [
            {"key": "job_id", "value": "{{job_id}}"}
          ]
        }
      }
    },
    {
      "name": "5. Get Result",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "http://127.0.0.1:7860/api/result?job_id={{job_id}}",
          "protocol": "http",
          "host": ["127", "0", "0", "1"],
          "port": "7860",
          "path": ["api", "result"],
          "query": [
            {"key": "job_id", "value": "{{job_id}}"}
          ]
        }
      }
    }
  ]
}

⚠️ IMPORTANT NOTES

  1. Local Server Must Be Running: 

    cd d:\webscreper
uvicorn api:app --port 7860

  2. For Hugging Face Deployment: Replace http://127.0.0.1:7860 with https://ubuntu593-alt-scraper-api.hf.space

    • ⚠️ Note: HF deployment needs to be updated first (see deployment guide)

  3. Save Job ID: Copy the job_id from step 3 to use in steps 4 & 5

  4. Polling: Call step 4 every 1-2 seconds until status becomes done

✅ VERIFICATION CHECKLIST

  • Health endpoint returns {"status": "alive"}
  • Status endpoint returns region/latency
  • Scanstart with query params returns job_id
  • Scanstart with JSON body returns job_id
  • Progress endpoint shows realtime updates
  • Result endpoint returns full report

ALL TESTS PASSED ✅