Skip to navigation
BotBye APIProtectionGood Bots

check

View as Markdown

Tells whether a request that declares itself a known crawler (a search engine, an SEO crawler and the like) really comes from that crawler.

Call it from your backend with the visitor’s IP address and User-Agent, before any page script could run — for example to let a genuine search-engine crawler through while treating an impostor that only copies its User-Agent as a bot.

Endpoint

POST https://verify.botbye.com/api/v1/protect/good-bot

This endpoint is served from verify.botbye.com, the same host as the request evaluation API, not from api.botbye.com.

Authentication

Send a personal access token in the X-Api-Key request header.

Request Body

FieldTypeRequiredDescription
ipstringYesThe visitor’s IP address as your backend received it: a single IPv4 or IPv6 address, without a zone id or a prefix length
user_agentstringYesThe visitor’s User-Agent header, unchanged

Response Structure

FieldTypeDescription
resultstringGOOD_BOT, FAKE_BOT or UNKNOWN
errorobjectPresent only when the request could not be checked
error.messagestringWhat was wrong with the call
resultMeaning
GOOD_BOTThe request comes from the crawler its User-Agent declares
FAKE_BOTThe User-Agent declares a known crawler, but the request does not come from it
UNKNOWNNo known crawler is declared, or the request could not be checked; judge it as ordinary traffic

Errors

The endpoint answers 200 even when the call fails: the response then carries result: "UNKNOWN" and an error naming the problem, for example:

  • Missing header 'X-Api-Key', Invalid API key, API key expired
  • Invalid request body: field 'ip' is not an IP address
  • Invalid request body: missing or invalid field 'user_agent'
  • Internal validation error

Since UNKNOWN is also the answer for ordinary traffic, check for error to tell a failed call from a checked one.

Accepted permissions Any valid API token (no specific permission required).

Authentication

X-Api-Keystring

Personal access token. Create it in your BotBye account under Profile → Personal Access Tokens, tick the scopes the endpoints you call require (see each endpoint’s Token scope), and send the token in the X-Api-Key request header. A token works only for the account it was created in.

Request

This endpoint expects an object.
ipstringRequired
The visitor's IPv4 or IPv6 address
user_agentstringRequired

The visitor’s User-Agent header

Response

success
resultenum
Allowed values:
errorobjectOptional