# BotThru

> Full guide for agents. Version 0.1.0. Updated 2026-11-17. Base URL https://botthru.com.

Do not send secrets or personal data. BotThru stores the need text from `/v1/ask` and does not store raw IP addresses.

## Order window

POST https://botthru.com/v1/ask

```json
{ "need": "what time is it in Chicago", "agent": "optional-name" }
```

```json
{
  "id": "6f1e5c3a-1d2b-4a8e-9c0d-112233445566",
  "status": "answered",
  "answer": "Current time in America/Chicago: ... BotThru only read the clock.",
  "suggestions": ["GET /api/time?tz=America%2FChicago"],
  "next_steps": "Use the timestamp above. Nothing was booked, sent, or changed.",
  "exchange_question": "Besides money, what could you offer in exchange for this service?",
  "offer": null
}
```

`answered` is only returned when time, uuid, echo, or whoami actually ran. `routed` is a Workers AI pointer (the task was not done). `unsupported` means the request was logged as demand and nothing ran. GET https://botthru.com/v1/ask/{id} returns the same shape without the need text. POST https://botthru.com/v1/ask/{id}/offer with `{"offer":"..."}` stores an offer. About 30 asks an hour. Bodies over 16KB are refused.

BotThru is a drive-thru, not a destination. Each response is small. There is no login. CORS allows any origin. Cookie, Authorization, Proxy-Authorization, X-Api-Key, and X-Auth-Token values are replaced with `[redacted]` on `/api/echo` and the MCP `echo` tool. Connecting-IP headers are redacted too.

Responses carry `X-BotThru-Bot` and `X-BotThru-Category`. Categories are `ai-crawler`, `ai-user-fetch`, `search-engine`, `other-bot`, `http-library`, `browser`, and `unknown`.

## Time

GET https://botthru.com/api/time

Optional query `tz` or `timezone`. IANA names only. Omitted means UTC. Unknown zones return HTTP 400.

```json
{
  "utc": "2026-11-17T15:04:00.000Z",
  "unix_ms": 1794913440000,
  "timezone": "America/New_York",
  "local": "2026-11-17T10:04:00-05:00",
  "offset": "-05:00",
  "abbreviation": "EST"
}
```

## UUID

GET https://botthru.com/api/uuid

```json
{ "uuid": "6f1e5c3a-1d2b-4a8e-9c0d-112233445566" }
```

## Echo

GET or POST https://botthru.com/api/echo

Returns the request as BotThru received it: method, URL, query, `country` (Cloudflare `request.cf.country`, else `CF-IPCountry`), `colo`, bot classification, and headers.

```json
{
  "method": "GET",
  "path": "/api/echo",
  "country": "US",
  "colo": "EWR",
  "bot": { "name": "curl", "category": "http-library", "reason": "user-agent contains \"curl/\"" },
  "headers": { "user-agent": "curl/8.7.1" }
}
```

## Who am I

GET https://botthru.com/api/whoami

```json
{
  "bot": { "name": "GPTBot", "category": "ai-crawler", "reason": "user-agent contains \"GPTBot\"" },
  "user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; GPTBot/1.2; +https://openai.com/gptbot)",
  "country": "US",
  "categories": ["ai-crawler", "ai-user-fetch", "search-engine", "other-bot", "http-library", "browser", "unknown"]
}
```

Named AI crawlers include GPTBot, OAI-SearchBot, ClaudeBot, Claude-SearchBot, PerplexityBot, Google-Extended, Applebot-Extended, CCBot, Amazonbot, meta-externalagent, DuckAssistBot, and cohere-ai. User-driven fetches include ChatGPT-User, Claude-User, and Perplexity-User. Googlebot, Bingbot, and Applebot are search engines. curl, python-requests, and axios are HTTP libraries.

## Stats

GET https://botthru.com/stats

```json
{
  "service": "botthru",
  "generated_at": "2026-11-17T15:04:00.000Z",
  "windows": {
    "last_24h": { "since": "2026-11-16T15:04:00.000Z", "total": 0, "by_bot": [], "by_category": [], "top_paths": [] },
    "last_7d": { "since": "2026-11-10T15:04:00.000Z", "total": 0, "by_bot": [], "by_category": [], "top_paths": [] },
    "all_time": { "since": null, "total": 0, "by_bot": [], "by_category": [], "top_paths": [] }
  }
}
```

Counts come from a D1 `visits` table. Logging runs after the response is sent and never changes the status code if it fails.

## MCP

POST https://botthru.com/mcp

Streamable HTTP. One JSON-RPC 2.0 message per request. Responds with `application/json` (no SSE stream). Stateless: no `MCP-Session-Id`. GET returns 405. DELETE returns 405. `notifications/initialized` returns 202 and an empty body.

Supported protocol versions: 2025-03-26, 2025-06-18, 2025-11-25.

Initialize:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "example", "version": "0.0.0" }
  }
}
```

Then POST `{"jsonrpc":"2.0","method":"notifications/initialized"}`.

tools/call:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "time", "arguments": { "timezone": "America/Chicago" } }
}
```

Tool errors (such as a bad time zone) return HTTP 200 with `result.isError: true`. Unknown tools are JSON-RPC `-32602`.

Discovery: https://botthru.com/.well-known/mcp.json and https://botthru.com/.well-known/agents.json.

## Discovery files

- https://botthru.com/robots.txt allows every crawler and lists AI crawlers explicitly. Sitemap: https://botthru.com/sitemap.xml.
- https://botthru.com/.well-known/agent-card.json is an A2A-style card for discovery. Do not send A2A tasks; use the JSON API or MCP.
- https://botthru.com/openapi.json describes the HTTP API.
