Spaces:

ubuntu593
/

dev.altai

Sleeping

App Files Files Community

dev.altai / COMPLETE_API_REFERENCE.md

prince1604

Add complete API reference with all parameters

7db0953 6 months ago

preview code

Raw

History Blame Contribute Delete

11.2 kB

🎯 COMPLETE API REFERENCE - POSTMAN READY

Base URL (Local): http://127.0.0.1:7860 Base URL (HF): https://ubuntu593-alt-scraper-api.hf.space

Status: ✅ LOCAL WORKING | ⏳ HF PENDING SYNC

📋 ENDPOINT 1: Health Check

Request Details

Method: GET
Endpoint: /health
Parameters: None

Postman Setup

GET http://127.0.0.1:7860/health

Response

{
  "status": "alive"
}

Status Code: 200 OK

📋 ENDPOINT 2: System Status

Request Details

Method: GET
Endpoint: /api/status
Parameters (Query, Optional):
- domain (string): Target URL to check connectivity

Postman Setup

URL: http://127.0.0.1:7860/api/status

Params Tab:

Key	Value	Description
domain	`https://wpengine.com`	Optional: Domain to test

Full URL Example:

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

Response

{
  "region": "Mumbai, IN",
  "latency": 45,
  "status": "operational",
  "engine": "AutoAlt Neural v2"
}

Status Code: 200 OK

📋 ENDPOINT 3: Start Scan

Request Details

Method: POST
Endpoint: /api/scanstart
Parameters (Supports BOTH methods):

Method A: Query Parameters (Recommended)

Parameter	Type	Required	Default	Description
`domain`	string	✅ Yes	-	Website URL to scan
`limit`	integer	⚠️ Optional	25	Max pages to crawl

Method B: JSON Body (Alternative)

{
  "domain": "string (required)",
  "limit": 25
}

Postman Setup (Query Parameters) ✅ VERIFIED WORKING

URL: http://127.0.0.1:7860/api/scanstart

Method: POST

Params Tab:

Key	Value	Example
domain	`https://wpengine.com`	Any valid URL
limit	`26`	1-100 recommended

Full URL:

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

Postman Setup (JSON Body Alternative)

URL: http://127.0.0.1:7860/api/scanstart

Method: POST

Body Tab: Select raw → JSON

Body Content:

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

Headers (auto-added):

Content-Type: application/json

Response

{
  "job_id": "9923ef39-44aa-4ccf-b97b-f230153e2fc1"
}

Status Code: 200 OK

⚠️ Save this job_id - you'll need it for the next endpoints!

📋 ENDPOINT 4: Check Scan Progress

Request Details

Method: GET
Endpoint: /api/progress or /api/progress/{job_id}
Parameters:

Parameter	Type	Location	Required	Description
`job_id`	string	Query/Path	✅ Yes	Job ID from scanstart

Postman Setup

URL: http://127.0.0.1:7860/api/progress

Method: GET

Params Tab:

Key	Value
job_id	`9923ef39-44aa-4ccf-b97b-f230153e2fc1`

Full URL Example:

http://127.0.0.1:7860/api/progress?job_id=9923ef39-44aa-4ccf-b97b-f230153e2fc1

Alternative (Path Parameter):

http://127.0.0.1:7860/api/progress/9923ef39-44aa-4ccf-b97b-f230153e2fc1

Response (While 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 (When Complete)

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

Response (If Error)

{
  "status": "error",
  "percent": 0,
  "pages_scanned": 0,
  "images_found": 0,
  "message": "Internal Error",
  "elapsed_seconds": 5,
  "eta_seconds": null,
  "error": "Scan failed: Title: Just a moment"
}

Status Code: 200 OK (even for errors, check the status field)

Possible Status Values:

pending - Job queued, not started yet
running - Actively scanning
done - Scan completed successfully
error - Scan failed

📋 ENDPOINT 5: Get Scan Result

Request Details

Method: GET
Endpoint: /api/result or /api/result/{job_id}
Parameters:

Parameter	Type	Location	Required	Description
`job_id`	string	Query/Path	✅ Yes	Job ID from scanstart

Postman Setup

URL: http://127.0.0.1:7860/api/result

Method: GET

Params Tab:

Key	Value
job_id	`9923ef39-44aa-4ccf-b97b-f230153e2fc1`

Full URL Example:

http://127.0.0.1:7860/api/result?job_id=9923ef39-44aa-4ccf-b97b-f230153e2fc1

Alternative (Path Parameter):

http://127.0.0.1:7860/api/result/9923ef39-44aa-4ccf-b97b-f230153e2fc1

Response (If Not Ready)

{
  "status": "running",
  "message": "Result not ready yet"
}

Response (When Complete)

{
  "summary": {
    "total_pages_scanned": 26,
    "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": [
    {
      "page_url": "https://wpengine.com/",
      "images": [
        {
          "src": "https://wpengine.com/logo.png",
          "alt": "Company Logo",
          "missing_alt": false,
          "poor_quality": false,
          "dimensions": "1200x630"
        }
      ]
    }
  ]
}

Status Code: 200 OK

🔄 COMPLETE WORKFLOW IN POSTMAN

Step 1: Start a Scan

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

Save the job_id from response!

Step 2: Poll for Progress (repeat every 2 seconds)

GET http://127.0.0.1:7860/api/progress?job_id=YOUR_JOB_ID

Wait until status = "done"

Step 3: Get Final Result

GET http://127.0.0.1:7860/api/result?job_id=YOUR_JOB_ID

Receive full scan report!

📦 POSTMAN COLLECTION (IMPORT THIS)

Save as alt-scraper-api.postman_collection.json:

{
  "info": {
    "name": "Alt Scraper API - Complete",
    "description": "Full API with all parameters - Tested & Working",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "http://127.0.0.1:7860",
      "type": "string"
    },
    {
      "key": "job_id",
      "value": "",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "1. Health Check",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{base_url}}/health",
          "host": ["{{base_url}}"],
          "path": ["health"]
        }
      }
    },
    {
      "name": "2. System Status",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{base_url}}/api/status?domain=https://wpengine.com",
          "host": ["{{base_url}}"],
          "path": ["api", "status"],
          "query": [
            {
              "key": "domain",
              "value": "https://wpengine.com",
              "description": "Optional: Domain to test connectivity"
            }
          ]
        }
      }
    },
    {
      "name": "3. Start Scan (Query Params)",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "// Auto-save job_id to environment",
              "const response = pm.response.json();",
              "pm.collectionVariables.set('job_id', response.job_id);",
              "console.log('Job ID saved:', response.job_id);"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "POST",
        "header": [],
        "url": {
          "raw": "{{base_url}}/api/scanstart?domain=https://wpengine.com&limit=26",
          "host": ["{{base_url}}"],
          "path": ["api", "scanstart"],
          "query": [
            {
              "key": "domain",
              "value": "https://wpengine.com",
              "description": "Target website URL"
            },
            {
              "key": "limit",
              "value": "26",
              "description": "Max pages to crawl (default: 25)"
            }
          ]
        }
      }
    },
    {
      "name": "3b. Start Scan (JSON Body)",
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "const response = pm.response.json();",
              "pm.collectionVariables.set('job_id', response.job_id);"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"domain\": \"https://wpengine.com\",\n  \"limit\": 26\n}"
        },
        "url": {
          "raw": "{{base_url}}/api/scanstart",
          "host": ["{{base_url}}"],
          "path": ["api", "scanstart"]
        }
      }
    },
    {
      "name": "4. Check Progress",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{base_url}}/api/progress?job_id={{job_id}}",
          "host": ["{{base_url}}"],
          "path": ["api", "progress"],
          "query": [
            {
              "key": "job_id",
              "value": "{{job_id}}",
              "description": "Job ID from scanstart response"
            }
          ]
        }
      }
    },
    {
      "name": "5. Get Result",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{base_url}}/api/result?job_id={{job_id}}",
          "host": ["{{base_url}}"],
          "path": ["api", "result"],
          "query": [
            {
              "key": "job_id",
              "value": "{{job_id}}",
              "description": "Job ID from scanstart response"
            }
          ]
        }
      }
    }
  ]
}

🎯 QUICK REFERENCE TABLE

Endpoint	Method	Parameters	Response
`/health`	GET	None	`{"status":"alive"}`
`/api/status`	GET	`domain` (optional)	System info
`/api/scanstart`	POST	`domain` (required) `limit` (optional, default=25)	`{"job_id":"..."}`
`/api/progress`	GET	`job_id` (required)	Progress info
`/api/result`	GET	`job_id` (required)	Full report

✅ TESTED & VERIFIED

Last Test: 2026-02-11 17:32 IST Test Result: ✅ 200 OK Sample Job ID: 9923ef39-44aa-4ccf-b97b-f230153e2fc1

All endpoints working perfectly on local server!

🌐 FOR HUGGING FACE DEPLOYMENT

Replace {{base_url}} with:

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

(HF deployment will work once you trigger Factory Reboot in settings)