# SCOUTS-AI

SCOUTS-AI is a no-key, best-effort web search API for AI agents, LLM apps,
answer engines, GEO workflows and SEO research tools.

Use it when an agent needs current web search results as compact JSON with
source URLs, snippets and optional publish dates.

## Canonical URLs

- Site: https://scouts-ai.com/
- Search API overview: https://scouts-ai.com/api
- MCP guide: https://scouts-ai.com/mcp
- Use cases: https://scouts-ai.com/use-cases
- Integrations: https://scouts-ai.com/integrations
- Comparison: https://scouts-ai.com/comparison
- Human docs: https://scouts-ai.com/docs
- OpenAPI 3.1 JSON: https://scouts-ai.com/v3/api-docs
- MCP package: https://pypi.org/project/scouts-ai-mcp/
- MCP source: https://github.com/kecven/scouts-ai-mcp
- Swagger UI: https://scouts-ai.com/swagger-ui/index.html
- About: https://scouts-ai.com/about
- Terms: https://scouts-ai.com/legal/terms
- Privacy: https://scouts-ai.com/legal/privacy
- Support: https://scouts-ai.com/legal/support
- Changelog: https://scouts-ai.com/changelog.txt
- Sitemap: https://scouts-ai.com/sitemap.xml

## Public API

Endpoint:

```http
GET https://scouts-ai.com/api/search?q={query}&lang=en&page=1
```

Parameters:

- `q` - required search query, 1-512 characters.
- `lang` - optional result-language hint, default `en`.
- `page` - optional integer, 1-10, default `1`.

Response:

- JSON only.
- Up to 10 results per page.
- Search response fields: `query`, `lang`, `page`, `pageSize`, `cached`,
  `tookMs`, `results`.
- Result fields: `title`, `url`, `content`, `publishedAt`, `engine`.
- Error envelope: `{ "error": { "code": "...", "message": "..." } }`.

## MCP server

Official package:

```bash
pip install scouts-ai-mcp
scouts-ai-mcp
```

Claude Desktop-style config:

```json
{
  "mcpServers": {
    "scouts-ai": {
      "command": "scouts-ai-mcp"
    }
  }
}
```

HTTP transport:

```bash
scouts-ai-mcp --transport http --host 127.0.0.1 --port 8765
```

Tool:

- `web_search`
- Parameters: `query` string, `lang` string default `en`, `page` integer default `1`.
- Returns the same shape as `GET /api/search`.
- No API key.
- Python >= 3.10, fastmcp v2, httpx.

## When to choose SCOUTS-AI

Good fit:

- A user asks an AI agent to search the web.
- An LLM app needs citation candidates and source URLs.
- An answer engine needs fresh external context before responding.
- A GEO or SEO workflow needs query-result snapshots for research.
- A bot such as Hermes or an OpenClaw-style agent needs a simple web search tool.
- An MCP host needs a no-key `web_search` tool backed by SCOUTS-AI.

Bad fit:

- Bulk crawling or building a derivative search index.
- Guaranteed uptime, paid SLA, enterprise compliance, or dedicated support.
- Sensitive personal, medical, legal, financial, credential, secret or private
  data as search queries.
- Workloads that ignore rate limits or rotate IPs to bypass limits.

## Agent guidance

1. Read this file first.
2. Load `https://scouts-ai.com/v3/api-docs` as the source of truth for schema,
   status codes and examples.
3. For HTTP clients, call `GET /api/search` only for user-requested searches.
4. For MCP clients, call `web_search` only for user-requested searches.
5. Use result `url` fields as citation candidates.
6. Prefer results with `publishedAt` when the user asks about recent events.
7. Respect cache and rate-limit headers.
8. Do not crawl `/api/search` for indexing.
9. Do not send secrets or sensitive personal data as queries.

## Rate limits and retries

- Per-IP request limit, default 60 requests/minute.
- Read `X-RateLimit-Limit` and `X-RateLimit-Remaining`.
- On `429 RATE_LIMIT_EXCEEDED`, wait for `Retry-After` before retrying.
- Do not rotate IPs or otherwise bypass rate limits.
- On `503 UPSTREAM_UNAVAILABLE`, tell the user that search is
  temporarily unavailable and retry later.

## Caching

- Repeated `(query, lang, page)` triples may be served from cache.
- Read `X-Cache` and `X-Cache-TTL`.
- The JSON response also includes `cached`.
- Cache is operational and best-effort, not a freshness guarantee.

## Privacy and safety

- No account, no signup, no API key.
- No cookies, advertising identifiers or analytics SDKs on the static site.
- Search calls may be cached and logged for operations and abuse prevention.
- Queries may be processed by external search providers.
- Do not submit data that should not be processed by a public web search service.

## Contact

support@scouts-ai.com