Bot WHOIS
Submit a botLook up a bot
DirectoryOperatorsCategoriesMethodologyAPIAboutContact
Submit a botLook up a bot
Directory/API
Developer reference · v1

The Bot WHOIS API

Query the full bot registry over HTTPS and get JSON back. The read endpoints below are public - no key required - and are the same data that powers this site.

Jump to endpoints

Introduction

The API mirrors everything in the public registry - every tracked bot, its operator, category, sentiment, published user-agents and IP ranges. Every response is JSON. All requests must be made over HTTPS; plain HTTP is refused.

Base URL. All endpoints are relative to https://botwhois.org/api/v1.

Response format

Every endpoint returns the same envelope. On success, success is true and the payload is in data. List endpoints add a meta object with pagination totals. On failure, success is false and error carries a human-readable message.

Success
{
  "success": true,
  "data": [ /* … */ ],
  "meta": { "total": 544, "skip": 0, "take": 50 }
}
Error
{
  "success": false,
  "error": "Invalid sentiment: Maybe"
}

Errors

The API uses conventional HTTP status codes. A 2xx is success, a 4xx is a problem with the request, and a 5xx is an error on our side.

StatusMeaningWhen
200okThe request succeeded.
400bad_requestA query parameter was malformed (e.g. an unknown sentiment, kind, or since value).
404not_foundNo bot, tag, or record matches the identifier.
500server_errorSomething went wrong on our end.
504timeoutAn upstream fetch (e.g. live community posts) timed out.

Authentication

The read endpoints documented here are public and need no authentication. Administrative writes - reviewing candidates, managing tags, running ingestion - require an admin key sent as Authorization: Bearer <ADMIN_API_KEY> and are not part of the public API. Contact us if you need write access.

The one exception is POST /api/v1/contact, which backs the contact form and is public and unauthenticated. It sends an email and writes nothing to the registry. It is rate-limited globally rather than per caller, so it can answer 429 under load, and it also returns 413, 415, 502 and 503 in addition to the statuses listed below.

Endpoints
GET/v1/bots

List bots

Returns a paginated list of tracked bots. Filter by category, operator sentiment, or kind; search by name or description; and page with take/skip. Pass since to fetch only records updated after a timestamp.

Query parameters
ParameterTypeDescription
qstringSearch bot name or description (substring match).
categorystringExact category, e.g. "AI Crawler" or "Search Engine Crawler".
sentimentstringOne of GoodBot, BadBot, Undecided.
kindstringOne of BOT, AGENT.
sortstringname_asc (default), name_desc, newest, updated.
takeintegerPage size, 1-200. Defaults to 50.
skipintegerOffset for pagination. Defaults to 0.
sinceISO 8601Return only bots with updatedAt after this timestamp.
Request
curl "https://botwhois.org/api/v1/bots?category=AI%20Crawler&take=1"
Response
{
  "success": true,
  "data": [
    {
      "id": "clx…",
      "name": "GPTBot",
      "operator": "OpenAI",
      "category": "AI Crawler",
      "sentiment": "GoodBot",
      "verificationStatus": "Verified",
      "kind": "BOT",
      "userAgents": "[\"GPTBot/1.0\"]",
      "ipRanges": "[\"…\"]",
      "operatorSlug": "openai",
      "botSlug": "gptbot"
      /* … plus the full bot record + sources[] */
    }
  ],
  "meta": { "total": 27, "skip": 0, "take": 1 }
}
GET/v1/bots/{id}

Retrieve a bot

Fetch the full record for a single bot by its id, including its sources and URLs. Returns 404 if no bot matches.

Request
curl https://botwhois.org/api/v1/bots/clx0000000000000000000000
Response
{
  "success": true,
  "data": {
    "id": "clx…",
    "name": "GPTBot",
    "operator": "OpenAI",
    "category": "AI Crawler",
    "sentiment": "GoodBot",
    "sources": [ { "sourceName": "Cloudflare" } ]
    /* … full bot record */
  }
}
GET/v1/tags

List tags

Returns every tag with its bot count. Tags are a lightweight cross-cutting label on top of categories.

Request
curl https://botwhois.org/api/v1/tags
Response
{
  "success": true,
  "data": [
    { "id": "…", "name": "AI", "slug": "ai", "botCount": 61 }
  ]
}
GET/v1/reddit/{botId}

Community posts

Returns Reddit discussion for a bot. Cached results are served directly from the registry; when nothing is cached the endpoint attempts a bounded live lookup, which may be unavailable. Best-effort - handle a non-200 or empty result.

Request
curl https://botwhois.org/api/v1/reddit/clx0000000000000000000000
Response
{
  "success": true,
  "data": [
    { "title": "…", "subreddit": "webdev", "url": "…", "upvotes": 342 }
  ]
}