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. Write operations - submitting a bot, reviewing candidates, managing tags - 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.

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 }
  ]
}