COMPLETE_API_REFERENCE.md

# 🎯 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
```json
{
  "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
```json
{
  "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)
```json
{
  "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**:
```json
{
  "domain": "https://wpengine.com",
  "limit": 26
}
```

**Headers** (auto-added):
```
Content-Type: application/json
```

### Response
```json
{
  "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)
```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
}
```

### Response (When Complete)
```json
{
  "status": "done",
  "percent": 100,
  "pages_scanned": 26,
  "images_found": 145,
  "message": "Completed",
  "elapsed_seconds": 25,
  "eta_seconds": null,
  "error": null
}
```

### Response (If Error)
```json
{
  "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)
```json
{
  "status": "running",
  "message": "Result not ready yet"
}
```

### Response (When Complete)
```json
{
  "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`:

```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)<br>`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)**