polysearch/API.md

# PolySearch API

A search API for AI agents. Submit queries, get structured results. Supports single and batch requests.

**Base URL:** `http://<host>:9876`

**Auth:** All endpoints except `/health` require a Bearer token.

```http
Authorization: Bearer <api_key>
```

---

## Quick reference

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/health` | GET | No | Ping the server |
| `/search` | POST | Yes | One query, one response |
| `/batch` | POST | Yes | Multiple queries, one response |
| `/metrics` | GET | Yes | Proxy pool health and usage |

---

## Authentication

The server operator provides an API key. Include it in every request (except `/health`):

```bash
curl -H "Authorization: Bearer <key>" http://localhost:9876/search ...
```

---

## `GET /health`

Check if the server is running.

```bash
curl http://localhost:9876/health
```

```json
{
  "success": true,
  "status": "ok",
  "uptime": 42.5,
  "proxyPool": {
    "total": 11,
    "alive": 11,
    "dead": 0,
    "requestsTotal": 47,
    "successRate": "91.5%",
    "hourlyUsage": 12
  }
}
```

---

## `POST /search`

Single search. Returns either image results, web results, or both.

```bash
curl -X POST http://localhost:9876/search \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "mars rover", "type": "image", "limit": 3}'
```

### Request

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `query` | string | yes | — | What to search for |
| `type` | string | no | `image` | `image`, `web`, or `both` |
| `limit` | number | no | `10` | Max results per type (1–50) |

### Response — Image results

```json
{
  "success": true,
  "query": "mars rover",
  "type": "image",
  "execution_time_ms": 3200,
  "image": {
    "engine": "duckduckgo",
    "total": 3,
    "results": [
      {
        "index": 1,
        "title": "NASA Perseverance Rover's Stunning Find...",
        "image_url": "https://scitechdaily.com/images/...jpg",
        "source_url": "https://scitechdaily.com/...",
        "domain": "scitechdaily.com",
        "width": 2560,
        "height": 1818,
        "thumbnail": "https://tse4.mm.bing.net/th?id=...",
        "engine": "duckduckgo"
      }
    ],
    "statistics": {
      "avg_width": 3200,
      "avg_height": 1989,
      "domains": {
        "scitechdaily.com": 1,
        "static1.simpleflyingimages.com": 2
      }
    }
  }
}
```

Each image result contains:

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Image description or caption |
| `image_url` | string | Direct URL to the image file |
| `source_url` | string | Page the image was found on |
| `domain` | string | Hosting domain |
| `width` | number | Image width (pixels) |
| `height` | number | Image height (pixels) |
| `thumbnail` | string | Thumbnail URL |
| `engine` | string | Search engine used |

### Response — Web results

When `type` is `web` or `both`:

```json
{
  "web": {
    "engine": "duckduckgo",
    "total": 3,
    "results": [
      {
        "index": 1,
        "title": "Quantum computing - Wikipedia",
        "url": "https://en.wikipedia.org/wiki/Quantum_computing",
        "domain": "en.wikipedia.org",
        "snippet": "A quantum computer is a computer that exploits quantum mechanical phenomena...",
        "engine": "duckduckgo"
      }
    ],
    "statistics": {
      "domains": {
        "en.wikipedia.org": 1
      }
    }
  }
}
```

### Response — Error

```json
{
  "success": false,
  "error": {
    "code": "ENGINE_FAILED",
    "message": "All search engines returned errors",
    "type": "Error"
  },
  "query": "obscure term",
  "timestamp": "2026-06-05T10:55:25.088Z"
}
```

---

## `POST /batch`

Run 2–50 queries in a single request. Queries execute concurrently. Results return when all are complete.

```bash
curl -X POST http://localhost:9876/batch \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"query": "vintage radio",  "type": "image", "limit": 2},
      {"query": "mars rover",     "type": "image", "limit": 2},
      {"query": "aurora borealis","type": "image", "limit": 2}
    ]
  }'
```

### Request

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `queries` | array | yes | 2–50 query objects |

Each query object:

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `query` | string | yes | — | Search term |
| `type` | string | no | `image` | `image`, `web`, or `both` |
| `limit` | number | no | `10` | Max results per type |

### Response

```json
{
  "success": true,
  "batch_size": 3,
  "execution_time_ms": 4511,
  "ok": 3,
  "fail": 0,
  "results": [
    {
      "index": 0,
      "query": "vintage radio",
      "type": "image",
      "success": true,
      "execution_time_ms": 4313,
      "results": { ... full search response ... },
      "errors": []
    }
  ],
  "metrics": {
    "hourly_usage": 7
  }
}
```

Each result mirrors the single `/search` response. Failed queries include an `error` field instead of `results`.

Use `batch_size` to verify all queries were accepted, and `ok` / `fail` for a quick success count.

---

## `GET /metrics`

Proxy pool statistics. Useful for monitoring health and utilization.

```bash
curl -H "Authorization: Bearer <key>" http://localhost:9876/metrics
```

```json
{
  "success": true,
  "metrics": {
    "totalProxies": 11,
    "alive": 11,
    "dead": 0,
    "circuitOpen": 0,
    "requestsTotal": 47,
    "successTotal": 43,
    "failureTotal": 4,
    "successRate": "91.5%",
    "hourlyUsageCurrent": 12,
    "byProvider": {
      "webshare": {
        "proxyCount": 10,
        "alive": 10,
        "requests": 47,
        "success": 43,
        "failure": 4,
        "avgLatencyMs": 3604,
        "successRate": "91.5%",
        "hourlyUsage": { "currentHour": 12 }
      }
    }
  }
}
```

---

## Notes

- **Rate limits** depend on the proxy provider. The system distributes requests evenly and opens circuit breakers when proxies fail repeatedly.
- **Timeouts** vary. Image searches typically take 2–15 seconds depending on query and network conditions.
- **Max batch size** is 50 queries per request.