API_DOCUMENTATION.md

# Antigravity SEO Scaler - API Documentation

Base URL: `http://localhost:7860` (or your deployed URL)

## 1. Start a New Scan
Initiates an asynchronous crawling and analysis job for a target domain.

- **Endpoint**: `/api/scanstart`
- **Method**: `POST`
- **Headers**: `Content-Type: application/json`
- **Body Parameters**:
    - `domain` (string, required): The URL of the website to scan (e.g., "https://example.com").
    - `limit` (integer, optional): Maximum number of pages to crawl. Default is `25`.

**Example Request (curl):**
```bash
curl -X POST "http://localhost:7860/api/scanstart" \
     -H "Content-Type: application/json" \
     -d '{"domain": "https://example.com", "limit": 50}'
```

**Example Response:**
```json
{
  "job_id": "8e8c40c5-77e0-4ad6-906a-53d038cd9fe7"
}
```

---

## 2. Check Scan Progress
Retrieves the real-time status of a running job. You can use either a path parameter or a query parameter.

### Option A: Path Parameter
- **Endpoint**: `/api/progress/{job_id}`
- **Method**: `GET`

### Option B: Query Parameter
- **Endpoint**: `/api/progress`
- **Method**: `GET`
- **Query Parameters**:
    - `job_id` (string, required): The ID returned by the start endpoint.

**Example Request:**
```bash
curl "http://localhost:7860/api/progress/8e8c40c5-77e0-4ad6-906a-53d038cd9fe7"
# OR
curl "http://localhost:7860/api/progress?job_id=8e8c40c5-77e0-4ad6-906a-53d038cd9fe7"
```

**Example Response:**
```json
{
  "status": "running",
  "percent": 45,
  "pages_scanned": 12,
  "images_found": 86,
  "message": "Scanning: https://example.com/about",
  "elapsed_seconds": 15,
  "eta_seconds": 20,
  "error": null
}
```
*Possible Statuses*: `pending`, `running`, `done`, `error`

---

## 3. Get Scan Results
Retrieves the final detailed JSON report. This should be called when the progress status is `done`.

### Option A: Path Parameter
- **Endpoint**: `/api/result/{job_id}`
- **Method**: `GET`

### Option B: Query Parameter
- **Endpoint**: `/api/result`
- **Method**: `GET`
- **Query Parameters**:
    - `job_id` (string, required): The ID of the completed job.

**Example Request:**
```bash
curl "http://localhost:7860/api/result/8e8c40c5-77e0-4ad6-906a-53d038cd9fe7"
```

**Example Response:**
```json
{
  "summary": {
    "total_pages_scanned": 50,
    "total_images_found": 320,
    "total_images_missing_alt": 45,
    "blocked_reason": null,
    "crawl_blocked": false
  },
  "details": [
    {
      "page_url": "https://example.com",
      "images": [ ... ]
    }
  ]
}
```

---

## 4. System Status
Checks the health and resource usage of the underlying server.

- **Endpoint**: `/api/status`
- **Method**: `GET`
- **Query Parameters**:
    - `domain` (string, optional): A target URL to check reachability for.

**Example Response:**
```json
{
  "cpu_percent": 12.5,
  "memory_percent": 45.2,
  "disk_usage": 60.1,
  "target_reachable": true
}
```

---

## 5. Health Check
Simple endpoint for load balancers or uptime monitors.

- **Endpoint**: `/health`
- **Method**: `GET`

**Example Response:**
```json
{ "status": "alive" }
```