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.

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):

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

---

GET /health

Check if the server is running.

curl http://localhost:9876/health

{
  "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.

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

{
  "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:

{
  "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

{
  "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.

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

{
  "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.

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

{
  "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.